@shundoo-ai/dsh-cosmic 1.0.19 → 1.0.21

package/skills/cosmic-build/scripts/kingscript_sdk_sync.py

@@ -0,0 +1,350 @@
+#!/usr/bin/env python3
+"""KingScript SDK sync: poll the target environment for its real SDK surface.
+
+The shipped SDK indexes under skills/cosmic-coding-script/references/sdk/ are
+a build-time snapshot and silently drift from the running Cosmic release
+(older environments lack newer types; newer business modules such as
+@constellation/* never appear in the snapshot). The platform now exposes
+``POST /kapi/v2/sysext/kingscript/dev/poll/sdk`` which returns a one-shot
+tempfile URL to a ZIP of the environment's actual ``@cosmic/*`` .d.ts
+declarations. This script turns that ZIP into a local, grep-friendly cache:
+
+    ~/.kd/kingscript-sdk/<envName>/
+      sdk-meta.json     generated_at / baseUrl / counts / zip sha256
+      type-index.tsv    <type>\t<module>\t<pkg slash>\t<pkg dot>   (D4 lookup)
+      dts/              the extracted .d.ts tree (method signatures)
+
+Cache is environment-level (not per-appRoot): the SDK surface depends on the
+Cosmic release, and every app-build command targets the default kd env.
+
+Commands:
+  ensure   sync only when the cache is missing or older than --ttl-hours
+  sync     force a fresh poll + download + index rebuild
+  status   report cache state without network access
+  lookup   resolve one type name against the cache (convenience for D4)
+
+Exit codes: 0 = cache ready (ensure/sync/lookup succeeded), 2 = sync failed
+or lookup miss. All output is a single JSON object on stdout.
+"""
+
+from __future__ import annotations
+
+import argparse
+import hashlib
+import json
+import os
+import re
+import shutil
+import sys
+import tempfile
+import time
+import urllib.error
+import urllib.request
+import zipfile
+from pathlib import Path
+
+_SCRIPTS_DIR = Path(__file__).resolve().parent
+if str(_SCRIPTS_DIR) not in sys.path:
+    sys.path.insert(0, str(_SCRIPTS_DIR))
+
+SDK_ROOT = Path.home() / ".kd" / "kingscript-sdk"
+POLL_SDK_PATH = "/kapi/v2/sysext/kingscript/dev/poll/sdk"
+DEFAULT_TTL_HOURS = 168  # one week; SDK moves with platform releases, not daily
+DOWNLOAD_TIMEOUT_SEC = 600
+# Package-level export file: "<module>/<pkg path>.d.ts" whose body lists the
+# environment's importable names in three shapes:
+#   export declare type X = $.<pkg>.X;          (type alias — the common case)
+#   export declare const X: $.<pkg>.X_C;        (value export; often pairs
+#                                                 with the same-name type, but
+#                                                 HttpClient-style const-only
+#                                                 exports exist too)
+#   export declare interface X { ... }          (direct interface declaration)
+# `export declare const enum X` is rejected by the (?!enum...) guard so the
+# keyword "enum" is never captured as a name. The module-root aggregate files
+# (declare global { namespace $ ... }) match none of these shapes and are
+# naturally excluded from the index.
+_EXPORT_LINE_RE = re.compile(
+    r"^export declare (?:type|const|interface) (?!enum\b)(\w+)",
+    re.MULTILINE)
+
+
+def _emit(payload: dict) -> None:
+    print(json.dumps(payload, ensure_ascii=False))
+
+
+def _fail(error_code: str, message: str, **extra) -> int:
+    _emit({"status": "failed", "errorCode": error_code, "message": message, **extra})
+    return 2
+
+
+def _load_env():
+    """Load the default kd environment (baseUrl + credentials)."""
+    from kd_env_loader import load_default_kd_env
+
+    env = load_default_kd_env()
+    if not env.get("baseUrl"):
+        raise RuntimeError("kd default environment has no baseUrl")
+    return env
+
+
+def _cache_dir(env_name: str) -> Path:
+    safe = re.sub(r"[^A-Za-z0-9_.-]", "_", env_name) or "default"
+    return SDK_ROOT / safe
+
+
+def _read_meta(cache: Path) -> dict:
+    meta_path = cache / "sdk-meta.json"
+    if not meta_path.is_file():
+        return {}
+    try:
+        return json.loads(meta_path.read_text(encoding="utf-8"))
+    except (json.JSONDecodeError, OSError):
+        return {}
+
+
+def _cache_state(cache: Path, ttl_hours: float) -> dict:
+    meta = _read_meta(cache)
+    if not meta:
+        return {"state": "missing", "cacheDir": str(cache)}
+    age_hours = max(0.0, (time.time() - float(meta.get("generatedAt") or 0)) / 3600)
+    state = "fresh" if age_hours <= ttl_hours else "stale"
+    return {
+        "state": state,
+        "cacheDir": str(cache),
+        "envName": meta.get("envName"),
+        "baseUrl": meta.get("baseUrl"),
+        "generatedAt": meta.get("generatedAt"),
+        "ageHours": round(age_hours, 1),
+        "modules": meta.get("modules"),
+        "dtsFiles": meta.get("dtsFiles"),
+        "types": meta.get("types"),
+        "zipSha256": meta.get("zipSha256"),
+        "typeIndexPath": str(cache / "type-index.tsv"),
+        "dtsDir": str(cache / "dts"),
+    }
+
+
+def _poll_sdk_url(server: dict) -> str:
+    """POST poll/sdk and return the one-shot tempfile download URL."""
+    import kd_api
+
+    base = (server.get("baseUrl") or "").rstrip("/")
+    resp = kd_api.post(base, POLL_SDK_PATH, server, {"appId": ""})
+    if resp.get("status") is not True:
+        raise RuntimeError(
+            f"poll/sdk failed: {resp.get('errorCode')} {resp.get('message') or ''}".strip())
+    data = str(resp.get("data") or "").strip()
+    if not data:
+        raise RuntimeError("poll/sdk returned no download url in data")
+    return base + "/" + data.lstrip("/")
+
+
+def _download(url: str, dest: Path, attempts: int = 3) -> str:
+    """Stream the tempfile ZIP to dest (with retry) and return its sha256.
+
+    The tempfile endpoint occasionally resets idle connections; mirror
+    _http_client's bounded retry so a flaky link does not fail the sync.
+    """
+    last_error: Exception | None = None
+    for attempt in range(1, attempts + 1):
+        digest = hashlib.sha256()
+        try:
+            request = urllib.request.Request(url, headers={"User-Agent": "kingscript-sdk-sync"})
+            with urllib.request.urlopen(request, timeout=DOWNLOAD_TIMEOUT_SEC) as resp, \
+                    open(dest, "wb") as stream:
+                while True:
+                    chunk = resp.read(1 << 20)
+                    if not chunk:
+                        break
+                    digest.update(chunk)
+                    stream.write(chunk)
+            return digest.hexdigest()
+        except (OSError, urllib.error.URLError) as exc:
+            last_error = exc
+            if attempt < attempts:
+                time.sleep(attempt)
+    raise RuntimeError(f"download failed after {attempts} attempts: {last_error}")
+
+
+def _safe_member_name(name: str) -> str:
+    """Reject absolute paths, drive letters, and .. traversal (zip slip)."""
+    normalized = name.replace("\\", "/")
+    if normalized.startswith("/") or ":" in normalized.split("/", 1)[0]:
+        raise RuntimeError(f"unsafe zip entry: {name!r}")
+    parts = [p for p in normalized.split("/") if p not in ("", ".")]
+    if any(p == ".." for p in parts):
+        raise RuntimeError(f"unsafe zip entry: {name!r}")
+    return "/".join(parts)
+
+
+def build_type_index(zip_path: Path) -> tuple[list[str], int]:
+    """Extract (type, module, pkg_slash, pkg_dot) rows from package-level .d.ts.
+
+    Returns (sorted rows, dts_file_count). A module-root aggregate file lives
+    directly under "<module>/" with no package segment and only contains
+    ``declare global`` blocks, so it never yields index rows.
+    """
+    rows: list[str] = []
+    dts_count = 0
+    with zipfile.ZipFile(zip_path) as bundle:
+        for info in bundle.infolist():
+            name = _safe_member_name(info.filename)
+            if not name.endswith(".d.ts"):
+                continue
+            dts_count += 1
+            segments = name[: -len(".d.ts")].split("/")
+            if len(segments) < 3:
+                continue  # module-root aggregate (module/file.d.ts): no export rows
+            module = "/".join(segments[:2])
+            pkg_slash = "/".join(segments[2:])
+            try:
+                text = bundle.read(info).decode("utf-8", errors="replace")
+            except (OSError, zipfile.BadZipFile):
+                continue
+            names = set()  # per-file: a same-name type + const pair is one row
+            for match in _EXPORT_LINE_RE.finditer(text):
+                names.add(match.group(1))
+            for name in sorted(names):
+                rows.append(
+                    f"{name}\t{module}\t{pkg_slash}\t{pkg_slash.replace('/', '.')}")
+    rows.sort()
+    return rows, dts_count
+
+
+def _write_cache(cache: Path, zip_path: Path, env: dict, server: dict,
+                 zip_sha: str) -> dict:
+    """Atomically (re)build the cache directory from the downloaded ZIP."""
+    rows, dts_count = build_type_index(zip_path)
+    modules = sorted({row.split("\t")[1] for row in rows})
+    tmp = Path(tempfile.mkdtemp(prefix=".tmp-", dir=str(cache.parent)))
+    try:
+        dts_dir = tmp / "dts"
+        dts_dir.mkdir()
+        with zipfile.ZipFile(zip_path) as bundle:
+            for info in bundle.infolist():
+                name = _safe_member_name(info.filename)
+                if not name:
+                    continue
+                target = dts_dir / name
+                if info.is_dir():
+                    target.mkdir(parents=True, exist_ok=True)
+                    continue
+                target.parent.mkdir(parents=True, exist_ok=True)
+                with bundle.open(info) as src, open(target, "wb") as dst:
+                    shutil.copyfileobj(src, dst)
+        (tmp / "type-index.tsv").write_text("\n".join(rows) + ("\n" if rows else ""),
+                                            encoding="utf-8")
+        meta = {
+            "generatedAt": int(time.time()),
+            "envName": env.get("envName") or "",
+            "baseUrl": server.get("baseUrl") or "",
+            "modules": len(modules),
+            "moduleList": modules,
+            "dtsFiles": dts_count,
+            "types": len(rows),
+            "zipSha256": zip_sha,
+            "apiPath": POLL_SDK_PATH,
+        }
+        (tmp / "sdk-meta.json").write_text(
+            json.dumps(meta, ensure_ascii=False, indent=2), encoding="utf-8")
+        backup = cache.with_name(cache.name + ".old")
+        shutil.rmtree(backup, ignore_errors=True)
+        if cache.is_dir():
+            cache.rename(backup)
+        tmp.rename(cache)
+        shutil.rmtree(backup, ignore_errors=True)
+    finally:
+        shutil.rmtree(tmp, ignore_errors=True)
+    return meta
+
+
+def do_sync(server: dict, env: dict) -> int:
+    cache = _cache_dir(str(env.get("envName") or "default"))
+    cache.parent.mkdir(parents=True, exist_ok=True)
+    try:
+        url = _poll_sdk_url(server)
+        with tempfile.NamedTemporaryFile(prefix="ks-sdk-", suffix=".zip",
+                                         dir=str(cache.parent), delete=False) as tmp_zip:
+            zip_path = Path(tmp_zip.name)
+        try:
+            zip_sha = _download(url, zip_path)
+            meta = _write_cache(cache, zip_path, env, server, zip_sha)
+        finally:
+            zip_path.unlink(missing_ok=True)
+    except Exception as exc:  # noqa: BLE001 - surface any sync failure as JSON
+        return _fail("KINGSCRIPT_SDK_SYNC_FAILED", str(exc),
+                     cacheDir=str(cache), baseUrl=server.get("baseUrl"))
+    state = _cache_state(cache, 0)
+    _emit({"status": "synced", **state, "moduleList": meta.get("moduleList")})
+    return 0
+
+
+def do_ensure(server: dict, env: dict, ttl_hours: float) -> int:
+    cache = _cache_dir(str(env.get("envName") or "default"))
+    state = _cache_state(cache, ttl_hours)
+    if state.get("state") == "fresh":
+        _emit({"status": "ready", "ttlHours": ttl_hours, **state})
+        return 0
+    return do_sync(server, env)
+
+
+def do_lookup(env_name: str, type_name: str) -> int:
+    cache = _cache_dir(env_name)
+    index = cache / "type-index.tsv"
+    if not index.is_file():
+        return _fail("KINGSCRIPT_SDK_CACHE_MISSING",
+                     f"no SDK cache for env {env_name!r}; run ensure first",
+                     cacheDir=str(cache))
+    pattern = re.compile(rf"^{re.escape(type_name)}\t")
+    hits = [line.rstrip("\n") for line in
+            index.read_text(encoding="utf-8").splitlines() if pattern.match(line)]
+    if not hits:
+        _emit({"status": "miss", "type": type_name, "cacheDir": str(cache)})
+        return 2
+    columns = ("type", "module", "packageSlash", "packageDot")
+    _emit({"status": "found", "type": type_name, "cacheDir": str(cache),
+           "matches": [dict(zip(columns, hit.split("\t"))) for hit in hits]})
+    return 0
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(
+        description="Poll the target Cosmic environment for its KingScript SDK")
+    sub = parser.add_subparsers(dest="command", required=True)
+    for name in ("ensure", "sync"):
+        cmd = sub.add_parser(name)
+        cmd.add_argument("--ttl-hours", type=float, default=DEFAULT_TTL_HOURS,
+                         help=f"cache freshness window (default {DEFAULT_TTL_HOURS}h; "
+                              "only used by ensure)")
+    sub.add_parser("status")
+    lookup = sub.add_parser("lookup")
+    lookup.add_argument("--type", required=True, help="exact type name, e.g. AbstractFormPlugin")
+    lookup.add_argument("--env", default="", help="kd env name (default: current default env)")
+    args = parser.parse_args()
+
+    if args.command == "lookup":
+        env_name = args.env or os.environ.get("KD_DEFAULT_ENV")
+        if not env_name:
+            try:
+                env_name = _load_env().get("envName")
+            except Exception as exc:  # noqa: BLE001 - config problems must not traceback
+                return _fail("KINGSCRIPT_SDK_ENV_UNAVAILABLE", str(exc))
+        return do_lookup(str(env_name or "default"), args.type)
+
+    try:
+        env = _load_env()
+    except Exception as exc:  # noqa: BLE001 - config problems must not traceback
+        return _fail("KINGSCRIPT_SDK_ENV_UNAVAILABLE", str(exc))
+
+    if args.command == "status":
+        state = _cache_state(_cache_dir(str(env.get("envName") or "default")),
+                            DEFAULT_TTL_HOURS)
+        _emit({"status": state.get("state"), **state})
+        return 0
+    if args.command == "sync":
+        return do_sync(env, env)
+    return do_ensure(env, env, args.ttl_hours)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/skills/cosmic-build/scripts/kingscript_source_gate.py

@@ -10,7 +10,7 @@ createScript write. This gate is that place.
 It mirrors compile_plugin_source.py's philosophy for the Java path:
 
 * A set of static source rules derived from the authoritative KingScript P0
-  constraints (rule/p0-group-*.md in kingscript-code-generator). The unambiguous
+  constraints (rule/p0-group-*.md in cosmic-coding-script). The unambiguous
   "always illegal in KingScript" constructs are hard ERRORS that block the
   write; the context-dependent runtime traps are WARNINGS that are reported with
   a fix hint but do not block (the gate cannot know a value is a BigDecimal, so
@@ -238,18 +238,19 @@ def _scan(rules, view: str) -> list[dict[str, Any]]:
 
 
 def _export_contract_issue(text: str, target_type: str) -> Optional[dict[str, Any]]:
-    if target_type.upper() not in PLUGIN_TARGET_TYPES:
+    if target_type.upper() not in PLUGIN_TARGET_TYPES and target_type.upper() != "KWC_CONTROLLER":
         return None
-    if re.search(r"export\s*\{[^}]*\bplugin\b[^}]*\}", text):
+    binding = "kwcController" if target_type.upper() == "KWC_CONTROLLER" else "plugin"
+    if re.search(rf"export\s*\{{[^}}]*\b{binding}\b[^}}]*\}}", text):
         return None
-    if re.search(r"export\s+(?:const|let|var)\s+plugin\b", text):
+    if re.search(rf"export\s+(?:const|let|var)\s+{binding}\b", text):
         return None
     return {
         "rule": "KS-EXPORT-CONTRACT",
         "line": 1,
         "column": 1,
-        "message": "plugin script does not export the required `plugin` binding",
-        "fix": "end the file with: let plugin = new MyPlugin(); export { plugin };",
+        "message": f"script does not export the required `{binding}` binding",
+        "fix": f"end the file with: let {binding} = new MyClass(); export {{ {binding} }};",
     }
 
 
@@ -344,7 +345,9 @@ def gate_source(
         phase = "syntax" if syntax.get("status") == "failed" else "static"
         message = (
             f"KingScript gate blocked the write: {len(errors)} error(s) violate the "
-            "P0 constraints; fix them before createScript (the write is irreversible)"
+            "P0 constraints; fix them before "
+            + ("KWC Controller deployment" if target_type.upper() == "KWC_CONTROLLER"
+               else "createScript (the write is irreversible)")
         )
         errorCode = "KINGSCRIPT_GATE_FAILED"
     return {
@@ -369,7 +372,7 @@ def main() -> int:
     parser.add_argument("--source-path", help="Path to a .ts KingScript source file")
     parser.add_argument("--content", help="Inline KingScript source")
     parser.add_argument("--content-file", help="Path to a file containing KingScript source")
-    parser.add_argument("--target-type", default="", help="Plugin target type (enforces export contract)")
+    parser.add_argument("--target-type", default="", help="Plugin target type or KWC_CONTROLLER (checks export contract)")
     parser.add_argument("--skip-syntax", action="store_true", help="Skip the tsc syntax layer (static only)")
     parser.add_argument("--timeout-sec", type=int, default=120)
     args = parser.parse_args()