@litfamily/lithermes 1.0.0

package/assets/lithermes-plugin/skills/frontend-ui-ux/scripts/design_intelligence.py

@@ -0,0 +1,128 @@
+#!/usr/bin/env python3
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+PLUGIN_ROOT = Path(__file__).resolve().parents[3]
+sys.path.insert(0, str(PLUGIN_ROOT))
+
+from uiux_runtime_common import ContractError, emit_error, emit_json
+
+from design_contract_validation import (
+    BETA2_SCHEMA_ID,
+    BETA_SCHEMA_ID,
+    SCHEMA_ID,
+    canonical_design_contract,
+    design_contract_report,
+    load_design_contract_path,
+    load_design_contract_stdin,
+    validate_design_contract,
+)
+from design_runtime import query_dataset
+
+DEFAULT_DATASET = Path(__file__).resolve().parents[1] / "resources" / "design-intelligence.json"
+
+# Exit-code contract for the Design Contract commands:
+#   0  the contract satisfies every rule; stdout carries one line of JSON
+#      {"issues": [], "schema": "<id>", "valid": true}
+#   1  the input parsed but broke rules; stdout carries the same envelope with a
+#      populated issues array
+#   2  the input could not be trusted at all (oversize, non-UTF-8, NUL byte, duplicate
+#      JSON key, trailing data, unreadable or non-regular file); a human sentence goes
+#      to stderr and stdout stays empty
+# Every command hands its code back to `run`, which hands it to SystemExit at the bottom
+# of this file. Nothing exits from inside a nested call, so buffered stdout is always
+# flushed by normal interpreter shutdown before the code reaches the caller.
+
+
+def parser() -> argparse.ArgumentParser:
+    root = argparse.ArgumentParser(description="LitHermes offline design intelligence")
+    commands = root.add_subparsers(dest="command", required=True)
+    validate = commands.add_parser(
+        "validate-design-contract",
+        help="check a Design Contract; exits 0 valid, 1 invalid, 2 untrusted input",
+    )
+    validate.add_argument("--contract", type=Path, help="contract path; defaults to stdin")
+    validate.add_argument("--json", action="store_true", help="stdout is always the JSON envelope")
+    canonical = commands.add_parser(
+        "canonical-design-contract",
+        help="emit the canonical hashable text of a valid Design Contract",
+    )
+    canonical.add_argument("--contract", type=Path, help="contract path; defaults to stdin")
+    query = commands.add_parser("query")
+    query.add_argument("--query", required=True)
+    query.add_argument("--domain", required=True)
+    query.add_argument("--limit", type=int, default=20)
+    query.add_argument("--dataset", type=Path, default=DEFAULT_DATASET)
+    query.add_argument("--json", action="store_true")
+    return root
+
+
+def _load_contract(contract: Path):
+    if contract is None:
+        return load_design_contract_stdin()
+    return load_design_contract_path(contract)
+
+
+def _report_untrusted(error: ContractError) -> int:
+    sys.stderr.write("design contract input rejected: {0}\n".format(error.detail))
+    return 2
+
+
+def _validate_command(contract: Path) -> int:
+    try:
+        value = _load_contract(contract)
+    except ContractError as error:
+        return _report_untrusted(error)
+    report = design_contract_report(value)
+    emit_json(report)
+    return 0 if report["evidence_eligible"] else 1
+
+
+def _canonical_command(contract: Path) -> int:
+    try:
+        value = _load_contract(contract)
+    except ContractError as error:
+        return _report_untrusted(error)
+    issues = validate_design_contract(value)
+    if issues:
+        sys.stderr.write("design contract is invalid; canonical text withheld:\n")
+        for issue in issues:
+            sys.stderr.write("  - {0}\n".format(issue))
+        return 1
+    if value.get("schema_id") == SCHEMA_ID:
+        sys.stderr.write(
+            "design contract v1alpha1 is diagnostic-only; canonical completion requires v1beta1 or v1beta2\n"
+        )
+        return 1
+    if value.get("schema_id") not in (BETA_SCHEMA_ID, BETA2_SCHEMA_ID):
+        sys.stderr.write("design contract schema is not canonical\n")
+        return 1
+    sys.stdout.write(canonical_design_contract(value))
+    return 0
+
+
+def run(arguments: list[str]) -> int:
+    args = parser().parse_args(arguments)
+    if args.command == "validate-design-contract":
+        return _validate_command(args.contract)
+    if args.command == "canonical-design-contract":
+        return _canonical_command(args.contract)
+    try:
+        emit_json(
+            query_dataset(
+                args.dataset,
+                query=args.query,
+                domain=args.domain,
+                limit=args.limit,
+            )
+        )
+        return 0
+    except ContractError as error:
+        return emit_error(error)
+
+
+if __name__ == "__main__":
+    raise SystemExit(run(sys.argv[1:]))

package/assets/lithermes-plugin/skills/frontend-ui-ux/scripts/design_runtime.py

@@ -0,0 +1,98 @@
+from __future__ import annotations
+
+import hashlib
+import stat
+from pathlib import Path
+from typing import Final
+
+from uiux_runtime_common import ContractError, JsonValue, parse_json_bytes, require_mapping
+
+# The packaged corpus identity lives with the corpus loader. The Design Contract does
+# not carry, pin, or depend on it.
+DATASET_SCHEMA: Final = "litfamily.design-intelligence/v1"
+DATASET_SHA256: Final = "a89011236a6ff14e12ec55fccbfab1bbd40ae34614cea5710c022121aa841bb8"
+DATASET_BYTES: Final = 1_023_482
+QUERY_MAX_BYTES: Final = 4096
+OUTPUT_RECORD_LIMIT: Final = 20
+DATASET_MAX_BYTES: Final = 4 * 1024 * 1024
+
+
+def _records(dataset: dict[str, JsonValue]) -> list[dict[str, JsonValue]]:
+    raw_records = dataset.get("records")
+    if not isinstance(raw_records, list) or not raw_records:
+        raise ContractError("DATASET_RECORD_INVALID", "records must be a non-empty array")
+    checked: list[dict[str, JsonValue]] = []
+    for index, candidate in enumerate(raw_records):
+        if not isinstance(candidate, dict):
+            raise ContractError("DATASET_RECORD_INVALID", f"record {index} is not an object")
+        required = ("record_id", "domain", "No")
+        if any(key not in candidate for key in required):
+            raise ContractError("DATASET_RECORD_INVALID", f"record {index} missing required fields")
+        if len(candidate) < 4:
+            raise ContractError("DATASET_RECORD_INVALID", f"record {index} has no content fields")
+        checked.append(candidate)
+    return checked
+
+
+def load_dataset(path: Path) -> tuple[dict[str, JsonValue], list[dict[str, JsonValue]]]:
+    try:
+        stat_result = path.lstat()
+    except OSError as error:
+        raise ContractError("DATASET_UNREADABLE", str(error)) from error
+    if path.is_symlink() or not stat.S_ISREG(stat_result.st_mode):
+        raise ContractError("DATASET_UNSAFE_PATH", str(path))
+    try:
+        raw = path.read_bytes()
+    except OSError as error:
+        raise ContractError("DATASET_UNREADABLE", str(error)) from error
+    try:
+        parsed = parse_json_bytes(raw, maximum_bytes=DATASET_MAX_BYTES)
+    except ContractError as error:
+        raise ContractError("DATASET_MALFORMED", error.detail) from error
+    dataset = require_mapping(parsed, code="DATASET_MALFORMED")
+    if dataset.get("schema_version") != DATASET_SCHEMA:
+        raise ContractError("DATASET_RECORD_INVALID", "unknown dataset schema")
+    records = _records(dataset)
+    digest = hashlib.sha256(raw).hexdigest()
+    if digest != DATASET_SHA256:
+        raise ContractError("DATASET_HASH_MISMATCH", digest)
+    return dataset, records
+
+
+def query_dataset(
+    path: Path,
+    *,
+    query: str,
+    domain: str,
+    limit: int,
+) -> dict[str, JsonValue]:
+    query_bytes = len(query.encode("utf-8"))
+    if query_bytes > QUERY_MAX_BYTES:
+        raise ContractError("QUERY_UTF8_TOO_LARGE", f"{query_bytes} > {QUERY_MAX_BYTES}")
+    if limit < 1 or limit > OUTPUT_RECORD_LIMIT:
+        raise ContractError("LIMIT_INVALID", f"limit must be 1..{OUTPUT_RECORD_LIMIT}")
+    _, records = load_dataset(path)
+    domains = {str(record["domain"]) for record in records}
+    if domain not in domains:
+        raise ContractError("UNKNOWN_DOMAIN", f"unknown domain: {domain}")
+    terms = [term for term in query.casefold().split() if term]
+    matches: list[dict[str, JsonValue]] = []
+    for record in records:
+        if record["domain"] != domain:
+            continue
+        searchable = " ".join(str(value) for value in record.values()).casefold()
+        if terms and not all(term in searchable for term in terms):
+            continue
+        matches.append(record)
+        if len(matches) == limit:
+            break
+    return {
+        "dataset_sha256": DATASET_SHA256,
+        "empty_result": not matches,
+        "fallback_applied": False,
+        "files_written": 0,
+        "network_access": False,
+        "query_utf8_bytes": query_bytes,
+        "records": matches,
+        "schema_id": "litfamily.design-intelligence-query/v1alpha1",
+    }

package/assets/lithermes-plugin/skills/frontend-ui-ux/scripts/import_design_intelligence.py

@@ -0,0 +1,56 @@
+#!/usr/bin/env python3
+from __future__ import annotations
+
+import argparse
+import hashlib
+import sys
+from pathlib import Path
+
+PLUGIN_ROOT = Path(__file__).resolve().parents[3]
+sys.path.insert(0, str(PLUGIN_ROOT))
+
+from uiux_runtime_common import ContractError, emit_error, emit_json
+
+from source_import import canonicalize
+from source_manifest import load_manifest
+
+DEFAULT_MANIFEST = Path(__file__).resolve().parents[1] / "resources" / "import-manifest.json"
+
+
+def parser() -> argparse.ArgumentParser:
+    result = argparse.ArgumentParser(description="Validate the pinned 34-source design-intelligence import")
+    result.add_argument("--source-root", required=True, type=Path)
+    result.add_argument("--manifest", type=Path, default=DEFAULT_MANIFEST)
+    result.add_argument("--check", action="store_true", required=True)
+    result.add_argument("--expect-records", type=int, required=True)
+    result.add_argument("--max-bytes", type=int, required=True)
+    return result
+
+
+def run(arguments: list[str]) -> int:
+    args = parser().parse_args(arguments)
+    try:
+        if args.expect_records != 2277 or args.max_bytes != 4_194_304:
+            raise ContractError("SOURCE_CONTRACT_INVALID", "approved record and byte bounds required")
+        source_root = args.source_root.resolve()
+        if not source_root.is_dir():
+            raise ContractError("SOURCE_ROOT_INVALID", str(source_root))
+        _, entries = load_manifest(args.manifest.resolve())
+        canonical = canonicalize(source_root, entries, args.expect_records, args.max_bytes)
+        emit_json(
+            {
+                "bytes": len(canonical),
+                "dataset_sha256": hashlib.sha256(canonical).hexdigest(),
+                "records": args.expect_records,
+                "status": "SOURCE_CONTRACT_PASS",
+            }
+        )
+        return 0
+    except (ContractError, OSError) as error:
+        if isinstance(error, ContractError):
+            return emit_error(error)
+        return emit_error(ContractError("SOURCE_IO_ERROR", str(error)))
+
+
+if __name__ == "__main__":
+    raise SystemExit(run(sys.argv[1:]))

package/assets/lithermes-plugin/skills/frontend-ui-ux/scripts/source_import.py

@@ -0,0 +1,144 @@
+from __future__ import annotations
+
+import csv
+import hashlib
+import io
+import json
+import re
+from pathlib import Path
+from typing import Final
+
+from source_manifest import LICENSE_SHA256, REPAIRED_JAVAFX_SHA256, SOURCE_COMMIT
+from uiux_runtime_common import ContractError, JsonValue
+
+DATASET_SHA256: Final = "a89011236a6ff14e12ec55fccbfab1bbd40ae34614cea5710c022121aa841bb8"
+DATASET_BYTES: Final = 1_023_482
+PLACEHOLDER = re.compile(r"(?i)(?:TODO|TBD|lorem\s+ipsum)")
+PUNCTUATION_ONLY = re.compile(r"^[^\w\s]+$", re.UNICODE)
+
+
+def _csv_rows(text: str, relative: str) -> list[list[str]]:
+    reader = csv.reader(io.StringIO(text, newline=""), strict=True)
+    try:
+        rows = list(reader)
+    except csv.Error as error:
+        raise ContractError("SOURCE_CSV_INVALID", f"{relative}: {error}") from error
+    if not rows:
+        raise ContractError("SOURCE_CSV_INVALID", f"{relative}: empty")
+    width = len(rows[0])
+    if any(len(row) != width for row in rows[1:]):
+        raise ContractError("SOURCE_CSV_INVALID", f"{relative}: row width drift")
+    return rows
+
+
+def _repair(text: str, entry: dict[str, JsonValue]) -> str:
+    repair = entry.get("repair")
+    if repair is None:
+        return text
+    expected = {
+        "occurrences": 18,
+        "repaired_sha256": REPAIRED_JAVAFX_SHA256,
+        "rule": "backslash_quote_to_rfc4180_double_quote",
+    }
+    if entry.get("path") != "src/ui-ux-pro-max/data/stacks/javafx.csv" or repair != expected:
+        raise ContractError("SOURCE_REPAIR_INVALID", str(entry.get("path")))
+    try:
+        _csv_rows(text, str(entry["path"]))
+    except ContractError:
+        pass
+    else:
+        raise ContractError("SOURCE_REPAIR_INVALID", "repair source unexpectedly parses")
+    if text.count('\\"') != 18:
+        raise ContractError("SOURCE_REPAIR_INVALID", "repair occurrence drift")
+    repaired = text.replace('\\"', '""')
+    if hashlib.sha256(repaired.encode("utf-8")).hexdigest() != REPAIRED_JAVAFX_SHA256:
+        raise ContractError("SOURCE_REPAIR_INVALID", "repaired hash drift")
+    return repaired
+
+
+def _source_bytes(source_root: Path, entry: dict[str, JsonValue]) -> bytes:
+    relative = Path(str(entry["path"]))
+    path = source_root / relative
+    if path.is_symlink() or not path.is_file():
+        raise ContractError("SOURCE_FILE_MISSING", str(relative))
+    raw = path.read_bytes()
+    if hashlib.sha256(raw).hexdigest() != entry.get("raw_sha256"):
+        raise ContractError("SOURCE_HASH_MISMATCH", str(relative))
+    if b"\x00" in raw:
+        raise ContractError("SOURCE_CSV_INVALID", f"{relative}: NUL")
+    return raw
+
+
+def _entry_records(source_root: Path, entry: dict[str, JsonValue]) -> list[dict[str, JsonValue]]:
+    relative = str(entry["path"])
+    try:
+        text = _source_bytes(source_root, entry).decode("utf-8", errors="strict")
+    except UnicodeDecodeError as error:
+        raise ContractError("SOURCE_CSV_INVALID", f"{relative}: UTF-8") from error
+    text = _repair(text.replace("\r\n", "\n").replace("\r", "\n"), entry)
+    rows = _csv_rows(text, relative)
+    header = rows[0]
+    if header != entry.get("header") or len(header) != len(set(header)):
+        raise ContractError("SOURCE_HEADER_MISMATCH", relative)
+    if len(rows) - 1 != entry.get("data_row_count"):
+        raise ContractError("SOURCE_ROW_COUNT_MISMATCH", relative)
+    selected = list(entry["selected_columns"])
+    positions = {column: header.index(column) for column in selected}
+    source_path = Path(relative)
+    stack = source_path.stem if source_path.parent.name == "stacks" else None
+    domain = f"stack/{stack}" if stack else source_path.stem
+    records: list[dict[str, JsonValue]] = []
+    for row_number, row in enumerate(rows[1:], start=2):
+        values = {column: row[positions[column]].strip(" \t\r\n\v\f") for column in selected}
+        if any(PLACEHOLDER.fullmatch(value) or (value and PUNCTUATION_ONLY.fullmatch(value)) for value in values.values()):
+            raise ContractError("SOURCE_TEXT_INVALID", f"{relative}: row {row_number}")
+        try:
+            source_no = int(values["No"], 10)
+        except ValueError as error:
+            raise ContractError("SOURCE_RECORD_INVALID", f"{relative}: row {row_number}") from error
+        if source_no < 1 or str(source_no) != values["No"]:
+            raise ContractError("SOURCE_RECORD_INVALID", f"{relative}: noncanonical No")
+        record: dict[str, JsonValue] = dict(values)
+        record["No"] = source_no
+        record["domain"] = domain
+        record["record_id"] = f"{domain}/{source_no}"
+        if stack:
+            record["stack"] = stack
+        records.append(record)
+    if len(records) != entry.get("normalized_record_count"):
+        raise ContractError("SOURCE_ROW_COUNT_MISMATCH", relative)
+    return records
+
+
+def canonicalize(
+    source_root: Path,
+    entries: list[dict[str, JsonValue]],
+    expected_records: int,
+    maximum_bytes: int,
+) -> bytes:
+    license_path = source_root / "LICENSE"
+    if license_path.is_symlink() or not license_path.is_file():
+        raise ContractError("SOURCE_LICENSE_INVALID", "LICENSE missing")
+    if hashlib.sha256(license_path.read_bytes()).hexdigest() != LICENSE_SHA256:
+        raise ContractError("SOURCE_LICENSE_INVALID", "LICENSE hash drift")
+    records: list[dict[str, JsonValue]] = []
+    record_ids: set[str] = set()
+    for entry in entries:
+        for record in _entry_records(source_root, entry):
+            record_id = str(record["record_id"])
+            if record_id in record_ids:
+                raise ContractError("SOURCE_RECORD_INVALID", f"duplicate {record_id}")
+            record_ids.add(record_id)
+            records.append(record)
+    if len(records) != expected_records:
+        raise ContractError("SOURCE_RECORD_COUNT_MISMATCH", f"{len(records)} != {expected_records}")
+    payload = {"records": records, "schema_version": "litfamily.design-intelligence/v1", "source_commit": SOURCE_COMMIT}
+    canonical = (
+        json.dumps(payload, ensure_ascii=False, sort_keys=True, separators=(",", ":"), allow_nan=False) + "\n"
+    ).encode("utf-8")
+    digest = hashlib.sha256(canonical).hexdigest()
+    if len(canonical) > maximum_bytes:
+        raise ContractError("SOURCE_OUTPUT_TOO_LARGE", f"{len(canonical)} > {maximum_bytes}")
+    if len(canonical) != DATASET_BYTES or digest != DATASET_SHA256:
+        raise ContractError("SOURCE_CANONICAL_MISMATCH", f"bytes={len(canonical)} sha256={digest}")
+    return canonical

package/assets/lithermes-plugin/skills/frontend-ui-ux/scripts/source_manifest.py

@@ -0,0 +1,65 @@
+from __future__ import annotations
+
+import hashlib
+import re
+from pathlib import Path
+from typing import Final
+
+from uiux_runtime_common import ContractError, JsonValue, parse_json_bytes, require_mapping
+
+MANIFEST_SHA256: Final = "9adf471d95aaf17e7866e1c7674cb1a101daae9abdab87c71c96a60f2a58e6fa"
+SOURCE_COMMIT: Final = "1307d97a72e6c1cda572cb65471ae5ce82995218"
+LICENSE_SHA256: Final = "738f69dfa83db5c347c678fb9d90e560877059f0de93a327c39001bff92dc014"
+REPAIRED_JAVAFX_SHA256: Final = "cb424eee50fff9fb6f503ce9a2793177e6eafa6eb7d2ba68561fb3e1b7301ba0"
+HASH = re.compile(r"^[0-9a-f]{64}$")
+
+
+def load_manifest(path: Path) -> tuple[dict[str, JsonValue], list[dict[str, JsonValue]]]:
+    if path.is_symlink() or not path.is_file():
+        raise ContractError("SOURCE_MANIFEST_INVALID", "manifest must be a regular file")
+    raw = path.read_bytes()
+    if hashlib.sha256(raw).hexdigest() != MANIFEST_SHA256:
+        raise ContractError("SOURCE_MANIFEST_INVALID", "manifest hash drift")
+    manifest = require_mapping(
+        parse_json_bytes(raw, maximum_bytes=256 * 1024),
+        code="SOURCE_MANIFEST_INVALID",
+    )
+    if set(manifest) != {"schema_version", "source", "sources"}:
+        raise ContractError("SOURCE_MANIFEST_INVALID", "manifest fields drift")
+    if manifest.get("schema_version") != "litfamily.source-import-manifest/v1":
+        raise ContractError("SOURCE_MANIFEST_INVALID", "manifest schema drift")
+    source = manifest.get("source")
+    if not isinstance(source, dict) or source.get("commit") != SOURCE_COMMIT:
+        raise ContractError("SOURCE_MANIFEST_INVALID", "source commit drift")
+    license_info = source.get("license")
+    if not isinstance(license_info, dict) or license_info.get("sha256") != LICENSE_SHA256:
+        raise ContractError("SOURCE_MANIFEST_INVALID", "license identity drift")
+    entries = manifest.get("sources")
+    if not isinstance(entries, list) or len(entries) != 34:
+        raise ContractError("SOURCE_MANIFEST_INVALID", "exactly 34 sources required")
+    paths: list[str] = []
+    for entry in entries:
+        if not isinstance(entry, dict):
+            raise ContractError("SOURCE_MANIFEST_INVALID", "source entry must be an object")
+        required = {
+            "data_row_count", "header", "normalized_record_count", "path", "profile",
+            "raw_sha256", "selected_columns",
+        }
+        if set(entry) not in (required, required | {"repair"}):
+            raise ContractError("SOURCE_MANIFEST_INVALID", "source entry fields drift")
+        source_path = entry.get("path")
+        if not isinstance(source_path, str) or not source_path.startswith("src/ui-ux-pro-max/data/"):
+            raise ContractError("SOURCE_MANIFEST_INVALID", "source path invalid")
+        paths.append(source_path)
+        if not isinstance(entry.get("header"), list) or not isinstance(entry.get("selected_columns"), list):
+            raise ContractError("SOURCE_MANIFEST_INVALID", f"column inventory invalid: {source_path}")
+        if not set(entry["selected_columns"]).issubset(set(entry["header"])) or "No" not in entry["selected_columns"]:
+            raise ContractError("SOURCE_MANIFEST_INVALID", f"selected columns invalid: {source_path}")
+        if HASH.fullmatch(str(entry.get("raw_sha256", ""))) is None:
+            raise ContractError("SOURCE_MANIFEST_INVALID", f"source hash invalid: {source_path}")
+        for key in ("data_row_count", "normalized_record_count"):
+            if not isinstance(entry.get(key), int) or isinstance(entry.get(key), bool) or entry[key] < 1:
+                raise ContractError("SOURCE_MANIFEST_INVALID", f"{key} invalid: {source_path}")
+    if len(set(paths)) != 34:
+        raise ContractError("SOURCE_MANIFEST_INVALID", "source paths must be unique")
+    return manifest, entries