sanka-cli 0.2.3__tar.gz → 0.2.5__tar.gz

{sanka_cli-0.2.3 → sanka_cli-0.2.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: sanka-cli
-Version: 0.2.3
+Version: 0.2.5
 Summary: Sanka command-line interface and migration runtime
 Project-URL: Repository, https://github.com/sankaHQ/sanka
 Project-URL: Issues, https://github.com/sankaHQ/sanka/issues
@@ -16,6 +16,7 @@ Classifier: Programming Language :: Python :: 3.13
 Classifier: Typing :: Typed
 Requires-Python: >=3.12
 Requires-Dist: click<9,>=8.1
+Requires-Dist: cryptography<52,>=43
 Requires-Dist: httpx<1,>=0.27
 Requires-Dist: keyring<26,>=25
 Requires-Dist: packaging<27,>=24
@@ -107,6 +108,17 @@ workflows, AI, Custom Code, and explicitly cloud-selected migrations retain
 their existing authentication requirements. Add `--json` to local lifecycle
 commands for the stable `sanka-cli/v1` response envelope.
 
+## Hosted repository runs
+
+`sanka cloud` uploads reviewed repository ZIPs, starts runs with an explicit
+credit cap, and reads status, receipts, and retained artifacts. When enabled by
+the operator, `cloud repair` makes one bounded patch attempt and `cloud certify`
+compares selected HTTP cases in a fresh worker. `cloud certificate-verify`
+verifies signed evidence online or with an explicitly trusted offline key ring.
+Every hosted command pins its workspace; paid operations require confirmation.
+See [Hosted repository runs](../../docs/cloud-runs.md) for inputs, pricing,
+verification scope, and revocation limits.
+
 ## Extension trust
 
 The manager verifies a trusted marketplace snapshot, manifest schema,
@@ -149,3 +161,22 @@ The distribution license expression is
 `Apache-2.0 AND AGPL-3.0-only`. Both license texts and the historical hosted
 CLI notice ship in the wheel and source archive. File-level SPDX identifiers
 are authoritative.
+
+
+### Compact lifecycle output
+
+Use `--compact-dsl` instead of `--json` on `scan`, `plan`, `apply`, `test`,
+`verify`, and extension management commands when an agent needs a short result.
+The flags are mutually exclusive; `--json` retains its existing contract.
+Compact output starts with `sanka-compact/v1 <command> <outcome> <migration_state>`
+then emits one `key=JSON-value` per line. Strings use JSON escaping, including
+newlines and quotes. Failures, warnings, plan hashes, and limitations are retained.
+Legacy aliases are not repeated. With full artifacts available, generated file
+contents and route source code are replaced by explicit omission counts and file
+names. Read the returned artifact for those details; a compact summary is not a
+replacement for the full report. `data.plan_hash` becomes the `plan_hash` line;
+use that core hash for apply, not a nested extension hash.
+
+Keep the lifecycle: scan → plan → apply → test → verify. An applied scaffold with
+manual gaps is not complete. Test establishes generated scope; scenario verification
+checks HTTP and database parity within the supplied fixtures and cases.

{sanka_cli-0.2.3 → sanka_cli-0.2.5}/README.md

@@ -77,6 +77,17 @@ workflows, AI, Custom Code, and explicitly cloud-selected migrations retain
 their existing authentication requirements. Add `--json` to local lifecycle
 commands for the stable `sanka-cli/v1` response envelope.
 
+## Hosted repository runs
+
+`sanka cloud` uploads reviewed repository ZIPs, starts runs with an explicit
+credit cap, and reads status, receipts, and retained artifacts. When enabled by
+the operator, `cloud repair` makes one bounded patch attempt and `cloud certify`
+compares selected HTTP cases in a fresh worker. `cloud certificate-verify`
+verifies signed evidence online or with an explicitly trusted offline key ring.
+Every hosted command pins its workspace; paid operations require confirmation.
+See [Hosted repository runs](../../docs/cloud-runs.md) for inputs, pricing,
+verification scope, and revocation limits.
+
 ## Extension trust
 
 The manager verifies a trusted marketplace snapshot, manifest schema,
@@ -119,3 +130,22 @@ The distribution license expression is
 `Apache-2.0 AND AGPL-3.0-only`. Both license texts and the historical hosted
 CLI notice ship in the wheel and source archive. File-level SPDX identifiers
 are authoritative.
+
+
+### Compact lifecycle output
+
+Use `--compact-dsl` instead of `--json` on `scan`, `plan`, `apply`, `test`,
+`verify`, and extension management commands when an agent needs a short result.
+The flags are mutually exclusive; `--json` retains its existing contract.
+Compact output starts with `sanka-compact/v1 <command> <outcome> <migration_state>`
+then emits one `key=JSON-value` per line. Strings use JSON escaping, including
+newlines and quotes. Failures, warnings, plan hashes, and limitations are retained.
+Legacy aliases are not repeated. With full artifacts available, generated file
+contents and route source code are replaced by explicit omission counts and file
+names. Read the returned artifact for those details; a compact summary is not a
+replacement for the full report. `data.plan_hash` becomes the `plan_hash` line;
+use that core hash for apply, not a nested extension hash.
+
+Keep the lifecycle: scan → plan → apply → test → verify. An applied scaffold with
+manual gaps is not complete. Test establishes generated scope; scenario verification
+checks HTTP and database parity within the supplied fixtures and cases.

{sanka_cli-0.2.3 → sanka_cli-0.2.5}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "sanka-cli"
-version = "0.2.3"
+version = "0.2.5"
 description = "Sanka command-line interface and migration runtime"
 readme = "README.md"
 requires-python = ">=3.12"
@@ -16,6 +16,7 @@ classifiers = [
 ]
 dependencies = [
   "click>=8.1,<9",
+  "cryptography>=43,<52",
   "httpx>=0.27,<1",
   "keyring>=25,<26",
   "packaging>=24,<27",

{sanka_cli-0.2.3 → sanka_cli-0.2.5}/src/sanka/cli/__init__.py

@@ -85,17 +85,21 @@ class _CliArgumentParser(argparse.ArgumentParser):
 
 def main(argv: list[str] | None = None) -> int:
     arguments = list(sys.argv[1:] if argv is None else argv)
-    json_errors = "--json" in arguments
+    json_errors = "--json" in arguments or "--compact-dsl" in arguments
     parser = _build_parser(json_errors=json_errors)
     try:
         args = parser.parse_args(arguments)
     except CliUsageError as error:
         command = arguments[0] if arguments and arguments[0] in SDK_COMMANDS else "sanka"
         return _print_cli_error(
-            argparse.Namespace(command=command, json=json_errors),
+            argparse.Namespace(
+                command=command, json=json_errors, compact_dsl="--compact-dsl" in arguments
+            ),
             error,
             exit_code=2,
         )
+    if getattr(args, "compact_dsl", False):
+        args.json = True
     if args.command is None:
         parser.print_help()
         return 0
@@ -173,12 +177,17 @@ def _json_result(
     return envelope
 
 
-def _print_json(payload: dict[str, Any]) -> None:
-    print(json.dumps(payload, ensure_ascii=False, indent=2, sort_keys=True))
+def _print_result(args: argparse.Namespace, payload: dict[str, Any]) -> None:
+    if getattr(args, "compact_dsl", False):
+        from sanka.cli._compact import render_compact
+
+        print(render_compact(payload))
+    else:
+        print(json.dumps(payload, ensure_ascii=False, indent=2, sort_keys=True))
 
 
 def _print_cli_error(args: argparse.Namespace, error: Exception, *, exit_code: int) -> int:
-    if getattr(args, "json", False):
+    if getattr(args, "json", False) or getattr(args, "compact_dsl", False):
         code = getattr(error, "code", None)
         details = getattr(error, "details", None)
         structured_error: dict[str, Any] = {
@@ -187,13 +196,14 @@ def _print_cli_error(args: argparse.Namespace, error: Exception, *, exit_code: i
         }
         if isinstance(details, dict) and details:
             structured_error["details"] = details
-        _print_json(
+        _print_result(
+            args,
             _json_result(
                 str(getattr(args, "command", "sanka") or "sanka"),
                 {"error": structured_error},
                 outcome="error",
                 migration_state="not_started" if exit_code == 2 else "failed",
-            )
+            ),
         )
     else:
         _terminal(args).failure(str(error))
@@ -221,9 +231,15 @@ def _build_parser(*, json_errors: bool = False) -> argparse.ArgumentParser:
 
     def presentation(sub: argparse.ArgumentParser, *, json_option: bool = True) -> None:
         if json_option:
-            sub.add_argument(
+            formats = sub.add_mutually_exclusive_group()
+            formats.add_argument(
                 "--json", action="store_true", help="print one sanka-cli/v1 JSON document"
             )
+            formats.add_argument(
+                "--compact-dsl",
+                action="store_true",
+                help="print a compact result; full generated code stays in artifacts",
+            )
         sub.add_argument("--no-color", action="store_true", help="disable ANSI color")
         detail = sub.add_mutually_exclusive_group()
         detail.add_argument("--quiet", action="store_true", help="print only outcome and errors")
@@ -414,7 +430,7 @@ def _build_parser(*, json_errors: bool = False) -> argparse.ArgumentParser:
         description=(
             "Check hashes, generated files, route coverage, and configured read-only HTTP "
             "comparisons. With --scenarios, replay a scenario file against the source "
-            "application and a candidate FastAPI app and diff status, body, declared "
+            "application and a candidate FastAPI or Flask app and diff status, body, declared "
             "headers, and database state; that mode needs no plan or generated manifest."
         ),
         epilog=(
@@ -436,6 +452,7 @@ def _build_parser(*, json_errors: bool = False) -> argparse.ArgumentParser:
         help="application repository root",
     )
     verify.add_argument("--to", help="select an application plan")
+    verify.add_argument("--settings", help="source Django settings module for scenario replay")
     verify.add_argument("--artifact-dir", default=DEFAULT_ARTIFACT_DIR)
     verify.add_argument("--output", default=None, help="generated FastAPI output directory")
     verify.add_argument(
@@ -667,8 +684,8 @@ def _extension_result(
     records: list[dict[str, Any]],
 ) -> int:
     data = {"operation": operation, "records": records}
-    if args.json:
-        _print_json(_json_result("extension", data, migration_state="not_started"))
+    if args.json or getattr(args, "compact_dsl", False):
+        _print_result(args, _json_result("extension", data, migration_state="not_started"))
         return 0
 
     terminal = _terminal(args)
@@ -895,8 +912,9 @@ def _print_application_result(
     *,
     migration_state: str,
 ) -> int:
-    if args.json:
-        _print_json(
+    if args.json or getattr(args, "compact_dsl", False):
+        _print_result(
+            args,
             _json_result(
                 command,
                 result.data,
@@ -904,7 +922,7 @@ def _print_application_result(
                 artifacts=list(result.artifacts),
                 limitations=list(result.limitations),
                 next_actions=list(result.next_actions),
-            )
+            ),
         )
     else:
         terminal = _terminal(args)
@@ -926,8 +944,9 @@ async def _cmd_plan(args: argparse.Namespace) -> int:
     engine = _engine(args.state)
     run_id = engine.create(spec)
     migration_plan = await engine.plan(run_id)
-    if args.json:
-        _print_json(
+    if args.json or getattr(args, "compact_dsl", False):
+        _print_result(
+            args,
             _json_result(
                 "plan",
                 {
@@ -953,7 +972,7 @@ async def _cmd_plan(args: argparse.Namespace) -> int:
                         ]
                     )
                 ],
-            )
+            ),
         )
     else:
         _print_plan(run_id, migration_plan)
@@ -995,8 +1014,9 @@ async def _cmd_apply(args: argparse.Namespace) -> int:
     if run.plan_json is None:
         raise ExecutionError("no plan for this spec yet; run `sanka plan` first")
     await engine.apply(run_id, plan_hash=args.plan_hash)
-    if args.json:
-        _print_json(
+    if args.json or getattr(args, "compact_dsl", False):
+        _print_result(
+            args,
             _json_result(
                 "apply",
                 {
@@ -1017,7 +1037,7 @@ async def _cmd_apply(args: argparse.Namespace) -> int:
                         ]
                     )
                 ],
-            )
+            ),
         )
     else:
         print(f"run {run_id}: applied")
@@ -1053,8 +1073,9 @@ async def _cmd_verify(args: argparse.Namespace) -> int:
     engine = _engine(args.state)
     run_id = engine.create(spec)
     verify_report = await engine.verify(run_id)
-    if args.json:
-        _print_json(
+    if args.json or getattr(args, "compact_dsl", False):
+        _print_result(
+            args,
             _json_result(
                 "verify",
                 {
@@ -1077,7 +1098,7 @@ async def _cmd_verify(args: argparse.Namespace) -> int:
                     "verified_within_scope" if verify_report.ok else "verification_failed"
                 ),
                 artifacts=[str(Path(args.state).resolve())],
-            )
+            ),
         )
     else:
         _print_verify(verify_report)

sanka_cli-0.2.5/src/sanka/cli/_compact.py

@@ -0,0 +1,50 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+"""Model-facing presentation of the existing result, with JSON-escaped values."""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+
+def _summary(value: Any, *, path: tuple[str, ...] = (), artifacts: bool = False) -> Any:
+    if isinstance(value, dict):
+        if path in {("files",), ("extension", "files")} and artifacts:
+            return {"names": sorted(value), "omitted_file_contents": len(value)}
+        result = {}
+        for name, item in value.items():
+            if name == "extension" and isinstance(item, dict):
+                # Core lifecycle responses repeat extension fields; retain differing hashes.
+                item = {k: v for k, v in item.items() if k not in value or value[k] != v}
+                if not item:
+                    continue
+            if (
+                name == "source"
+                and {"classification", "method"} <= value.keys()
+                and isinstance(item, str)
+                and artifacts
+            ):
+                result["omitted_source_characters"] = len(item)
+            else:
+                result[name] = _summary(item, path=(*path, name), artifacts=artifacts)
+        return result
+    if isinstance(value, list):
+        return [_summary(item, path=(*path, "[]"), artifacts=artifacts) for item in value]
+    return value
+
+
+def render_compact(payload: dict[str, Any]) -> str:
+    """One header, then key=JSON lines. Never truncate failures, warnings or hashes."""
+    lines = [" ".join(str(payload[k]) for k in ("command", "outcome", "migration_state"))]
+    lines[0] = "sanka-compact/v1 " + lines[0]
+    data = _summary(payload["data"], artifacts=bool(payload.get("artifacts")))
+    for key, value in data.items():
+        # Escape even extension-defined keys so a newline cannot forge another record.
+        label = key if key.isidentifier() else json.dumps(key, ensure_ascii=False)
+        lines.append(label + "=" + json.dumps(value, ensure_ascii=False, separators=(",", ":")))
+    for key in ("artifacts", "limitations", "next_actions"):
+        if payload.get(key):
+            lines.append(
+                key + "=" + json.dumps(payload[key], ensure_ascii=False, separators=(",", ":"))
+            )
+    return "\n".join(lines)

{sanka_cli-0.2.3 → sanka_cli-0.2.5}/src/sanka/runtime/extensions/lifecycle.py

@@ -820,7 +820,7 @@ class ApplicationLifecycle:
         written, so the source fingerprint legitimately differs from any reviewed plan and
         a plan may not exist yet. The extension lock still has to match its recommendation
         exactly; only the plan, fingerprint, and artifact checks that guard apply and test
-        are skipped, because replay writes nothing into the project.
+        are skipped, because replay only writes verification artifacts in its artifact directory.
         """
         explicit_env_names = _canonical_environment_names(explicit_env_names)
         fingerprint = fingerprint_repository(self.project_root)
@@ -839,7 +839,6 @@ class ApplicationLifecycle:
         if result.outcome != "success":
             self._raise_failure(result)
         data = dict(result.data)
-        data["extension"] = result.data
         return ExtensionResult(
             outcome="success",
             data=data,

{sanka_cli-0.2.3 → sanka_cli-0.2.5}/src/sanka_cli/__init__.py

@@ -1,4 +1,4 @@
 # SPDX-License-Identifier: Apache-2.0
 __all__ = ["__version__"]
 
-__version__ = "0.2.3"
+__version__ = "0.2.5"

sanka_cli-0.2.5/src/sanka_cli/certificates.py

@@ -0,0 +1,98 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Public certificate input and verification helpers; no hosted execution code."""
+
+from __future__ import annotations
+
+import base64
+import json
+import re
+from pathlib import Path
+from typing import Any
+from urllib.parse import unquote, urlsplit
+
+from cryptography.exceptions import InvalidSignature
+from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PublicKey
+
+
+def canonical_bytes(value: Any) -> bytes:
+    return json.dumps(
+        value, sort_keys=True, separators=(",", ":"), ensure_ascii=True, allow_nan=False
+    ).encode("utf-8")
+
+
+def read_json(path: Path, maximum: int = 192 * 1024) -> Any:
+    with path.open("rb") as stream:
+        data = stream.read(maximum + 1)
+    if len(data) > maximum:
+        raise ValueError("JSON file exceeds its size limit")
+    return json.loads(data)
+
+
+def load_scenarios(path: Path) -> list[dict[str, Any]]:
+    cases = read_json(path, 48 * 1024)
+    if not isinstance(cases, list) or not 1 <= len(cases) <= 50:
+        raise ValueError("Cases must be a JSON array containing 1 to 50 requests")
+    seen, normalized = set(), []
+    for case in cases:
+        if not isinstance(case, dict) or set(case) - {"id", "method", "path", "json_body"}:
+            raise ValueError("Each case accepts only id, method, path and json_body")
+        identifier, method, value = case.get("id"), case.get("method"), case.get("path")
+        if (
+            not isinstance(identifier, str)
+            or not re.fullmatch(r"[A-Za-z0-9][A-Za-z0-9_-]{0,63}", identifier)
+            or identifier in seen
+            or method not in {"GET", "POST", "PUT", "PATCH", "DELETE"}
+            or not isinstance(value, str)
+            or not 1 <= len(value) <= 1000
+        ):
+            raise ValueError("Each case needs a unique ID, supported method and local HTTP path")
+        seen.add(identifier)
+        parsed, decoded = urlsplit(value), unquote(value)
+        if (
+            not value.startswith("/")
+            or value.startswith("//")
+            or parsed.scheme
+            or parsed.netloc
+            or parsed.fragment
+            or "\\" in decoded
+            or any(ord(char) < 32 or ord(char) > 126 for char in decoded)
+            or ".." in decoded.split("?", 1)[0].split("/")
+        ):
+            raise ValueError("Case paths must be local ASCII HTTP paths without traversal")
+        body = case.get("json_body")
+        if len(canonical_bytes({"body": body})) > 8192 or (method == "GET" and body is not None):
+            raise ValueError("Case bodies are limited to 8 KiB; GET cannot have a body")
+        normalized.append({"id": identifier, "method": method, "path": value, "json_body": body})
+    if len(canonical_bytes(normalized)) > 47 * 1024:
+        raise ValueError("The normalized certificate scope exceeds its size limit")
+    return normalized
+
+
+def verify_certificate(document: dict[str, Any], key_document: dict[str, Any]) -> dict[str, Any]:
+    """Verify using keys supplied by the caller's chosen trusted source only."""
+    signed = document.get("certificate", document)
+    key_document = key_document.get("data", key_document)
+    try:
+        payload = signed["payload"]
+        if (
+            signed["algorithm"] != "Ed25519"
+            or signed["encoding"] != "sorted-ascii-json-v1"
+            or payload["schema_version"] != "developer-certificate-v1"
+            or payload["issuer"] != "https://api-v2.sanka.com"
+            or not isinstance(payload, dict)
+        ):
+            raise ValueError("Unsupported certificate issuer or signature format")
+        matches = [row for row in key_document["keys"] if row["key_id"] == signed["key_id"]]
+        if len(matches) != 1 or matches[0].get("algorithm") != "Ed25519":
+            raise ValueError("The signing key is not in the selected trusted key ring")
+        key = Ed25519PublicKey.from_public_bytes(
+            base64.b64decode(matches[0]["public_key_base64"], validate=True)
+        )
+        key.verify(
+            base64.b64decode(signed["signature_base64"], validate=True), canonical_bytes(payload)
+        )
+    except InvalidSignature as error:
+        raise ValueError("Certificate signature is invalid") from error
+    except (KeyError, TypeError, AttributeError) as error:
+        raise ValueError("Certificate or trusted key ring has an invalid format") from error
+    return payload

{sanka_cli-0.2.3 → sanka_cli-0.2.5}/src/sanka_cli/client.py

@@ -87,16 +87,43 @@ class SankaApiClient:
         path: str,
         *,
         params: dict[str, Any] | None = None,
+        headers: dict[str, str] | None = None,
+        max_bytes: int | None = None,
     ) -> tuple[bytes, dict[str, str]]:
         """Fetch a non-JSON body (currently only the Custom Code bundle download).
 
         Returns headers alongside the payload so the caller can verify the digest the
         server reports without a second request.
         """
+        request_headers = self._headers()
+        request_headers.update(headers or {})
+        if max_bytes is not None:
+            with self.client.stream(
+                method.upper(),
+                path,
+                headers=request_headers,
+                params=params,
+            ) as response:
+                content = bytearray()
+                for chunk in response.iter_bytes(chunk_size=65536):
+                    if len(content) + len(chunk) > max_bytes:
+                        raise APIError(
+                            status_code=413, message="API artifact exceeds its size limit"
+                        )
+                    content.extend(chunk)
+                if response.status_code >= 400:
+                    self._raise_for_response(
+                        httpx.Response(
+                            response.status_code,
+                            content=bytes(content),
+                            headers=response.headers,
+                        )
+                    )
+                return bytes(content), dict(response.headers)
         response = self.client.request(
             method.upper(),
             path,
-            headers=self._headers(),
+            headers=request_headers,
             params=params,
         )
         if response.status_code >= 400: