@passioncode-ai/fabric-agent-adapter 0.39.1 → 0.40.0

package/plugins/fabric-agent-adapter/skills/building-fabric-services/scripts/fabric_jsvalue.py

@@ -0,0 +1,310 @@
+"""JavaScript's view of JSON values, once for the whole kit (FAA-65, layer L0).
+
+The contract's answers are computed by TypeScript, so a kit that reads JSON the way Python does disagrees with them on
+the edges: `5.0` is a count, an integer beyond a double is Infinity, `String({"toString": 1})` throws, object keys
+that look like array indexes come first. Every reader in the kit takes those semantics from here:
+
+- ``js_string`` (``String()``), ``show`` (the contract's ``show``: ``String()``, or JSON where it would throw),
+  ``json_stringify`` (``JSON.stringify``), ``js_to_number`` (``Number()``), ``double``, ``safe_integer``;
+- ``same`` (``===``) and ``contains``, ``get`` with the ``MISSING`` sentinel for an absent member;
+- ``jcs`` (RFC 8785 canonical JSON) and the number formatting it shares with ``js_string``.
+
+Standard library only; nothing here imports another kit module.
+"""
+from __future__ import annotations
+
+import math
+import re
+from typing import Any, Dict, List, Tuple
+
+
+def js_number_string(value: float) -> str:
+    """ECMAScript Number::toString, which RFC 8785 §3.2.2.3 prescribes."""
+    if value == 0:
+        return "0"
+    if value < 0:
+        return "-" + js_number_string(-value)
+    digits, exponent = _shortest(value)
+    k, n = len(digits), len(digits) + exponent
+    if k <= n <= 21:
+        return digits + "0" * (n - k)
+    if 0 < n <= 21:
+        return digits[:n] + "." + digits[n:]
+    if -6 < n <= 0:
+        return "0." + "0" * (-n) + digits
+    e = n - 1
+    mantissa = digits if k == 1 else digits[0] + "." + digits[1:]
+    return "%se%s%d" % (mantissa, "+" if e >= 0 else "-", abs(e))
+
+
+def _shortest(value: float) -> Tuple[str, int]:
+    """The shortest round-trip digits of a positive finite double (Python's repr is shortest round-trip)."""
+    text = repr(value)
+    mantissa, _, exp = text.partition("e")
+    whole, _, frac = mantissa.partition(".")
+    digits = (whole + frac).lstrip("0")
+    exponent = (int(exp) if exp else 0) - len(frac)
+    if not digits:
+        return "0", 0
+    stripped = digits.rstrip("0")
+    exponent += len(digits) - len(stripped)
+    return stripped, exponent
+
+
+JSON_ESCAPES = {'"': '\\"', "\\": "\\\\", "\b": "\\b", "\f": "\\f", "\n": "\\n", "\r": "\\r", "\t": "\\t"}
+
+
+def json_string_literal(value: str) -> str:
+    out = ['"']
+    for ch in value:
+        code = ord(ch)
+        if 0xD800 <= code <= 0xDFFF:
+            raise TypeError("a lone surrogate has no canonical form")
+        if ch in JSON_ESCAPES:
+            out.append(JSON_ESCAPES[ch])
+        elif code < 0x20:
+            out.append("\\u%04x" % code)
+        else:
+            out.append(ch)
+    out.append('"')
+    return "".join(out)
+
+
+def jcs(value: Any) -> str:
+    """RFC 8785: members sorted by UTF-16 code units, numbers in ECMAScript form, strings as JSON.stringify
+    escapes them. Refuses what has no canonical form: a non-finite number, a lone surrogate, a non-JSON value.
+    A JSON number is a double: an integer beyond 2**53 is written as JavaScript would write it."""
+    if value is None:
+        return "null"
+    if value is True:
+        return "true"
+    if value is False:
+        return "false"
+    if isinstance(value, int):
+        if abs(value) < 2 ** 53:
+            return str(value)
+        try:
+            return js_number_string(float(value))
+        except OverflowError:
+            raise TypeError("a number beyond a double has no canonical form") from None
+    if isinstance(value, float):
+        if not math.isfinite(value):
+            raise TypeError("a non-finite number has no canonical form")
+        return js_number_string(value)
+    if isinstance(value, str):
+        return json_string_literal(value)
+    if isinstance(value, list):
+        return "[" + ",".join(jcs(item) for item in value) + "]"
+    if isinstance(value, dict):
+        if not all(isinstance(key, str) for key in value):
+            raise TypeError("only string member names have a canonical form")
+        keys = sorted(value, key=lambda key: key.encode("utf-16-be", "surrogatepass"))
+        return "{" + ",".join(json_string_literal(key) + ":" + jcs(value[key]) for key in keys) + "}"
+    raise TypeError("%s has no canonical form" % type(value).__name__)
+
+
+MISSING = object()
+
+
+def js_string(value: Any) -> str:
+    """String(value) for a JSON value."""
+    if value is MISSING:
+        return "undefined"
+    if value is None:
+        return "null"
+    if value is True:
+        return "true"
+    if value is False:
+        return "false"
+    if isinstance(value, float):
+        if math.isnan(value):
+            return "NaN"
+        if math.isinf(value):
+            return "Infinity" if value > 0 else "-Infinity"
+        return js_number_string(value)
+    if isinstance(value, int):
+        if abs(value) < 2 ** 53:
+            return str(value)
+        try:
+            return js_number_string(float(value))
+        except OverflowError:  # a JSON number beyond a double is Infinity in JavaScript
+            return "Infinity" if value > 0 else "-Infinity"
+    if isinstance(value, dict):
+        return "[object Object]"
+    if isinstance(value, list):
+        return ",".join("" if item is None else js_string(item) for item in value)
+    return str(value)
+
+
+def get(value: Any, key: str) -> Any:
+    return value.get(key, MISSING) if isinstance(value, dict) else MISSING
+
+
+def get_string(value: Any, key: str) -> str:
+    return js_string(get(value, key))
+
+
+def is_number(value: Any) -> bool:
+    return isinstance(value, (int, float)) and not isinstance(value, bool)
+
+
+def double(value: Any) -> float:
+    """A JSON number as JavaScript holds it: the nearest double, and an integer beyond the double range ±Infinity."""
+    try:
+        return float(value)
+    except OverflowError:
+        return math.inf if value > 0 else -math.inf
+
+
+def same(a: Any, b: Any) -> bool:
+    """JavaScript's === (and a Set's SameValueZero) on parsed JSON: an object equals only itself."""
+    if a is MISSING or b is MISSING:
+        return a is b
+    if isinstance(a, (dict, list)) or isinstance(b, (dict, list)):
+        return a is b
+    if isinstance(a, bool) or isinstance(b, bool):
+        return isinstance(a, bool) and isinstance(b, bool) and a == b
+    if is_number(a) and is_number(b):
+        return double(a) == double(b)  # 2**53 + 1 is 2**53 in JavaScript
+    return type(a) is type(b) and a == b
+
+
+def contains(items: List[Any], value: Any) -> bool:
+    return any(same(item, value) for item in items)
+
+
+#: The characters JavaScript's StringToNumber trims: WhiteSpace and LineTerminator (ECMA-262 §12.2, §12.3).
+_JS_SPACE = "\t\n\v\f\r              

  　"
+
+
+_JS_DECIMAL = re.compile(r"[+-]?(?:(?:[0-9]+\.?[0-9]*|\.[0-9]+)(?:[eE][+-]?[0-9]+)?|Infinity)", re.ASCII)
+
+
+_JS_RADIX = re.compile(r"0(?:[xX](?P<x>[0-9a-fA-F]+)|[oO](?P<o>[0-7]+)|[bB](?P<b>[01]+))", re.ASCII)
+
+
+def js_to_number(value: Any) -> float:
+    """Number(value) for a JSON value, as JavaScript reads it; NaN for what it cannot read as a number."""
+    if value is MISSING:
+        return math.nan
+    if value is None:
+        return 0.0
+    if isinstance(value, bool):
+        return 1.0 if value else 0.0
+    if is_number(value):
+        try:
+            return float(value)
+        except OverflowError:
+            return math.inf if value > 0 else -math.inf
+    if isinstance(value, list):
+        return js_to_number(js_string(value))  # Number([2]) is Number("2"); Number([]) is 0
+    if isinstance(value, str):
+        text = value.strip(_JS_SPACE)
+        if text == "":
+            return 0.0
+        if _JS_DECIMAL.fullmatch(text):
+            return float(text.replace("Infinity", "inf"))
+        radix = _JS_RADIX.fullmatch(text)
+        if radix:
+            digits, base = next((radix.group(k), b) for k, b in (("x", 16), ("o", 8), ("b", 2)) if radix.group(k))
+            return double(int(digits, base))
+    return math.nan
+
+
+def safe_integer(value: Any) -> bool:
+    if isinstance(value, int) and not isinstance(value, bool):
+        return abs(value) <= 2 ** 53 - 1  # checked before any float: a 400-digit integer would overflow
+    return isinstance(value, float) and math.isfinite(value) and value.is_integer() and abs(value) <= 2 ** 53 - 1
+
+
+def objects(value: Any) -> List[Dict[str, Any]]:
+    return [item for item in value if isinstance(item, dict)] if isinstance(value, list) else []
+
+
+def indexed_objects(value: Any) -> List[Tuple[Dict[str, Any], int]]:
+    """The object items of an array with their index in the array as written, so an instancePath names the item it
+    flags even when a non-object precedes it (the contract's ``indexed``)."""
+    return [(item, i) for i, item in enumerate(value) if isinstance(item, dict)] if isinstance(value, list) else []
+
+
+class Unshowable(Exception):
+    pass
+
+
+def strict_string(value: Any) -> str:
+    """String(value), raising where JavaScript's String() throws: an object whose own ``toString`` is not a function
+    (every own member of parsed JSON is data), directly or inside an array it joins."""
+    if isinstance(value, dict):
+        if "toString" in value:
+            raise Unshowable()
+        return "[object Object]"
+    if isinstance(value, list):
+        return ",".join("" if item is None else strict_string(item) for item in value)
+    return js_string(value)
+
+
+_INDEX_KEY = re.compile(r"0|[1-9][0-9]*", re.ASCII)
+
+
+def js_keys(value: Dict[str, Any]) -> List[str]:
+    """An object's own keys in the order JavaScript lists them: array-index keys ("0" … "4294967294", no leading zero)
+    ascending, then the others in the order written."""
+    index = sorted((k for k in value if _INDEX_KEY.fullmatch(k) and int(k) <= 2 ** 32 - 2), key=int)
+    taken = set(index)
+    return index + [k for k in value if k not in taken]
+
+
+def json_string(text: str) -> str:
+    """JSON.stringify of a string (well-formed, ES2019): a lone surrogate is escaped as \\uXXXX, never refused."""
+    out = ['"']
+    for ch in text:
+        code = ord(ch)
+        if ch in JSON_ESCAPES:
+            out.append(JSON_ESCAPES[ch])
+        elif code < 0x20 or 0xD800 <= code <= 0xDFFF:
+            out.append("\\u%04x" % code)
+        else:
+            out.append(ch)
+    out.append('"')
+    return "".join(out)
+
+
+def json_stringify(value: Any) -> str:
+    """JSON.stringify for a parsed JSON value: members in JavaScript's key order, numbers as JavaScript writes them, a
+    lone surrogate escaped."""
+    if isinstance(value, dict):
+        return "{" + ",".join(json_string(k) + ":" + json_stringify(value[k]) for k in js_keys(value)) + "}"
+    if isinstance(value, list):
+        return "[" + ",".join(json_stringify(v) for v in value) + "]"
+    if value is None:
+        return "null"
+    if isinstance(value, bool):
+        return "true" if value else "false"
+    if is_number(value):
+        text = js_string(value)
+        return "null" if text in ("NaN", "Infinity", "-Infinity") else text
+    return json_string(value)
+
+
+def show(value: Any) -> str:
+    """The contract's ``show``: String(value), or the value's JSON where String() would throw."""
+    try:
+        return strict_string(value)
+    except Unshowable:
+        return json_stringify(value)
+
+
+def key_of(*parts: Any) -> str:
+    """The contract's ``keyOf``: a collision-free key over JSON values, JSON.stringify of the parts (an absent value
+    is null inside an array, as JavaScript writes it)."""
+    return json_stringify([None if part is MISSING else part for part in parts])
+from typing import Any
+
+
+def json_equal(a: Any, b: Any) -> bool:
+    """The contract's jsonEqual: arrays in order, objects by their members, primitives as JavaScript's ===."""
+    if isinstance(a, list) or isinstance(b, list):
+        return isinstance(a, list) and isinstance(b, list) and len(a) == len(b) and all(json_equal(x, y) for x, y in zip(a, b))
+    if isinstance(a, dict) or isinstance(b, dict):
+        return isinstance(a, dict) and isinstance(b, dict) and len(a) == len(b) and all(k in b and json_equal(a[k], b[k]) for k in a)
+    return same(a, b)

package/plugins/fabric-agent-adapter/skills/building-fabric-services/scripts/fabric_kit.py

@@ -0,0 +1,243 @@
+#!/usr/bin/env python3
+"""The service kit as a versioned set of modules: build its manifest, install it into a service, report a copy's state.
+
+The kit is not one file. ``kit.json`` beside this script lists every module in dependency order, per language, with
+the kit modules it imports and its sha256, and ``history`` keeps the sha256 of every earlier release, so a copy in a
+service can be told apart: ``current``, ``older`` (with the release it came from), or ``modified``.
+
+    fabric_kit.py install <service-dir> [--lang py|node] [--module NAME ...] [--all] [--dry-run] [--force]
+    fabric_kit.py status <service-dir> [--json]
+    fabric_kit.py build [--check]          # maintainers: refresh kit.json from the sources
+
+``install`` copies the closure of the named modules (default ``fabric_service`` / ``fabric-service``) and nothing else.
+It refuses to overwrite a file it does not recognise (a ``modified`` copy) unless ``--force``. ``status`` also names a
+module a present module imports that is missing from the folder: the copy would fail when that code path runs.
+Standard library only. Exit codes: 0 done or all current, 1 a problem (missing, modified, refused), 2 usage.
+"""
+from __future__ import annotations
+
+import argparse
+import ast
+import hashlib
+import json
+import os
+import re
+import shutil
+import sys
+from pathlib import Path
+from typing import Dict, List
+
+HERE = Path(__file__).resolve().parent
+MANIFEST = HERE / "kit.json"
+LANGS = {"py": "python", "node": "node"}
+DEFAULT_ROOT = {"python": "fabric_service", "node": "fabric-service"}
+
+
+def _sha256(path: Path) -> str:
+    return hashlib.sha256(path.read_bytes()).hexdigest()
+
+
+def python_imports(path: Path, modules: List[str]) -> List[str]:
+    """The kit modules a Python file imports, at any depth of its code (a lazy import is a dependency too)."""
+    found = set()
+    for node in ast.walk(ast.parse(path.read_text(encoding="utf-8"))):
+        if isinstance(node, ast.Import):
+            found.update(a.name for a in node.names if a.name in modules)
+        elif isinstance(node, ast.ImportFrom) and node.module in modules:
+            found.add(node.module)
+    found.discard(path.stem)
+    return sorted(found)
+
+
+def node_imports(path: Path, modules: List[str]) -> List[str]:
+    """The kit modules an ES module imports (static `from './x.mjs'` and dynamic `import('./x.mjs')`)."""
+    text = path.read_text(encoding="utf-8")
+    found = set(re.findall(r"""(?:from|import\()\s*['"]\./([A-Za-z0-9_-]+)\.mjs['"]""", text)) & set(modules)
+    found.discard(path.stem)
+    return sorted(found)
+
+
+def load_manifest() -> Dict:
+    return json.loads(MANIFEST.read_text(encoding="utf-8"))
+
+
+def build(check: bool = False) -> List[str]:
+    """Refresh every module's imports and sha256 in kit.json, and record this release's digests in its history.
+    Returns what changed (with check=True nothing is written)."""
+    manifest = load_manifest()
+    changed = []
+    for lang, entries in (("python", manifest["python"]), ("node", manifest["node"])):
+        names = [e["module"] for e in entries]
+        for entry in entries:
+            path = HERE / entry["file"]
+            imports = (python_imports if lang == "python" else node_imports)(path, names)
+            digest = _sha256(path)
+            if entry.get("imports") != imports or entry.get("sha256") != digest:
+                changed.append(entry["file"])
+                entry["imports"], entry["sha256"] = imports, digest
+    data = sorted({d for e in manifest["python"] + manifest["node"] for d in e.get("data", [])})
+    digests = {d: _sha256(HERE / d) for d in data}
+    if manifest.get("data") != digests:
+        changed.append("data files")
+        manifest["data"] = digests
+    current = {e["file"]: e["sha256"] for e in manifest["python"] + manifest["node"]}
+    current.update(digests)
+    if manifest.setdefault("history", {}).get(manifest["version"]) != current:
+        manifest["history"][manifest["version"]] = current
+        changed.append("kit.json history %s" % manifest["version"])
+    if changed and not check:
+        MANIFEST.write_text(json.dumps(manifest, indent=1) + "\n", encoding="utf-8")
+    return changed
+
+
+def closure(entries: List[Dict], roots: List[str]) -> List[Dict]:
+    """The named modules and everything they import, in the manifest's (dependency) order."""
+    by_name = {e["module"]: e for e in entries}
+    unknown = [r for r in roots if r not in by_name]
+    if unknown:
+        raise SystemExit("unknown kit module: %s (the manifest lists %s)" % (", ".join(unknown), ", ".join(by_name)))
+    wanted, stack = set(), list(roots)
+    while stack:
+        name = stack.pop()
+        if name not in wanted:
+            wanted.add(name)
+            stack.extend(by_name[name]["imports"])
+    return [e for e in entries if e["module"] in wanted]
+
+
+def state_of(path: Path, manifest: Dict) -> Dict:
+    """`current`, `older` with the release a copy came from, or `modified` (a digest no release had)."""
+    digest = _sha256(path)
+    if any(e["file"] == path.name and e["sha256"] == digest for e in manifest["python"] + manifest["node"]) or \
+            manifest.get("data", {}).get(path.name) == digest:
+        return {"state": "current", "version": manifest["version"]}
+    for version, files in sorted(manifest.get("history", {}).items(), key=lambda kv: [int(x) for x in re.findall(r"[0-9]+", kv[0])], reverse=True):
+        if files.get(path.name) == digest:
+            return {"state": "older", "version": version}
+    return {"state": "modified", "version": None}
+
+
+def status(service_dir: Path) -> Dict:
+    manifest = load_manifest()
+    report = {"kit": manifest["version"], "files": [], "missing": []}
+    for lang in ("python", "node"):
+        entries = manifest[lang]
+        present = [e for e in entries if (service_dir / e["file"]).is_file()]
+        for e in present:
+            report["files"].append({"file": e["file"], **state_of(service_dir / e["file"], manifest)})
+        names = {e["module"] for e in present}
+        by_name = {e["module"]: e for e in entries}
+        def reader(path: Path, modules: List[str]) -> List[str]:
+            try:
+                return (python_imports if lang == "python" else node_imports)(path, modules)
+            except (SyntaxError, ValueError):  # a copy someone broke is already `modified`; its imports are unknown
+                return []
+        # What each copy imports is read from the copy itself (an older release imports other modules than this one);
+        # a module it lacks would be installed at this release, so that module's own imports are followed too.
+        queue = [(e["file"], reader(service_dir / e["file"], list(by_name))) for e in present]
+        reported = set()
+        for e in present:
+            for d in e.get("data", []):
+                if (service_dir / d).is_file():
+                    if d not in [f["file"] for f in report["files"]]:
+                        report["files"].append({"file": d, **state_of(service_dir / d, manifest)})
+                elif d not in reported:
+                    reported.add(d)
+                    report["missing"].append({"file": e["file"], "needs": d})
+        while queue:
+            importer, deps = queue.pop(0)
+            for dep in deps:
+                if dep in names or dep in reported:
+                    continue
+                reported.add(dep)
+                report["missing"].append({"file": importer, "needs": by_name[dep]["file"]})
+                for d in by_name[dep].get("data", []):  # the data a missing module reads at run time
+                    if not (service_dir / d).is_file() and d not in reported:
+                        reported.add(d)
+                        report["missing"].append({"file": by_name[dep]["file"], "needs": d})
+                queue.append((by_name[dep]["file"], by_name[dep]["imports"]))
+    return report
+
+
+def install(service_dir: Path, lang: str, modules: List[str], dry_run: bool = False, force: bool = False) -> Dict:
+    manifest = load_manifest()
+    entries = manifest[lang]
+    roots = modules or [DEFAULT_ROOT[lang]]
+    plan = closure(entries, roots)
+    result = {"kit": manifest["version"], "copied": [], "kept": [], "refused": []}
+    files = []
+    for e in plan:
+        files.append(e["file"])
+        files.extend(d for d in e.get("data", []) if d not in files)
+    for name in files:
+        target = service_dir / name
+        if target.is_file():
+            st = state_of(target, manifest)
+            if st["state"] == "current":
+                result["kept"].append(name)
+                continue
+            if st["state"] == "modified" and not force:
+                result["refused"].append(name)
+                continue
+        result["copied"].append(name)
+    if not dry_run and not result["refused"]:
+        service_dir.mkdir(parents=True, exist_ok=True)
+        for name in result["copied"]:
+            tmp = service_dir / (".%s.tmp" % name)
+            shutil.copyfile(HERE / name, tmp)
+            os.replace(tmp, service_dir / name)
+    return result
+
+
+def main(argv: List[str]) -> int:
+    parser = argparse.ArgumentParser(prog="fabric_kit.py", description=__doc__.split("\n\n")[0])
+    sub = parser.add_subparsers(dest="cmd", required=True)
+    p_install = sub.add_parser("install", help="copy a module's closure into a service")
+    p_install.add_argument("dir", type=Path)
+    p_install.add_argument("--lang", choices=sorted(LANGS), default="py")
+    p_install.add_argument("--module", action="append", default=[])
+    p_install.add_argument("--all", action="store_true", help="every module of the language")
+    p_install.add_argument("--dry-run", action="store_true")
+    p_install.add_argument("--force", action="store_true", help="overwrite a copy the kit does not recognise")
+    p_status = sub.add_parser("status", help="the state of the kit copies in a service")
+    p_status.add_argument("dir", type=Path)
+    p_status.add_argument("--json", action="store_true")
+    p_build = sub.add_parser("build", help="refresh kit.json from the sources (maintainers)")
+    p_build.add_argument("--check", action="store_true")
+    args = parser.parse_args(argv)
+    if args.cmd == "build":
+        changed = build(args.check)
+        print(("kit.json is out of date: " if args.check else "rebuilt: ") + ", ".join(changed) if changed else "kit.json is up to date")
+        return 1 if (changed and args.check) else 0
+    if args.cmd == "status":
+        report = status(args.dir)
+        if args.json:
+            print(json.dumps(report, indent=2))
+        else:
+            for f in report["files"]:
+                print("%-9s %s%s" % (f["state"], f["file"], " (%s)" % f["version"] if f["state"] == "older" else ""))
+            for m in report["missing"]:
+                print("missing   %s, which %s imports" % (m["needs"], m["file"]))
+            if not report["files"]:
+                print("no kit module in %s" % args.dir)
+        bad = not report["files"] or report["missing"] or any(f["state"] != "current" for f in report["files"])
+        return 1 if bad else 0
+    lang = LANGS[args.lang]
+    known = [e["module"] for e in load_manifest()[lang]]
+    modules = known if args.all else args.module
+    unknown = [m for m in modules if m not in known]
+    if unknown:
+        print("no such %s kit module: %s (kit.json lists %s)" % (lang, ", ".join(unknown), ", ".join(known)), file=sys.stderr)
+        return 2
+    result = install(args.dir, lang, modules, args.dry_run, args.force)
+    for name in result["copied"]:
+        print(("would copy " if args.dry_run else "copied     ") + name)
+    for name in result["kept"]:
+        print("current    " + name)
+    for name in result["refused"]:
+        print("refused    %s: the copy there is not one the kit released; --force overwrites it" % name)
+    return 1 if result["refused"] else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv[1:]))