sylo-ignition 0.1.0

package/scripts/resource_write.py

@@ -0,0 +1,171 @@
+#!/usr/bin/env python3
+"""Allowlist-gated atomic write of a project resource file.
+
+For ignition_resource_write tool. Enforces:
+  - operator-managed write-allowlist (project must be present + enabled)
+  - forbidden paths (.resources, digest files, .bin, var/, local config, thumbnails)
+  - JSON files must parse before writing (no corruption on disk)
+  - atomic replace via temp file
+  - new resource folders get a scaffold resource.json (scan-compatible)
+
+resource.json of EXISTING resources is never written — the gateway owns it.
+"""
+
+from __future__ import annotations
+
+import argparse
+import hashlib
+import json
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+from _allowlist import gate_writes, load_allowlist
+from _ignition import load_config, project_dir, resolve_project
+from _json_out import emit, emit_error
+
+FORBIDDEN_SUFFIXES = (".bin", ".idb", ".png", ".jpg", ".jpeg", ".gif", ".webp", ".zip", ".gwbk")
+FORBIDDEN_NAMES = {"thumbnail.png"}
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--project", default="")
+    parser.add_argument("--path", required=True, help="file path relative to project root")
+    parser.add_argument("--content", default=None, help="file content (string)")
+    parser.add_argument("--content-file", default=None, help="read content from this file instead")
+    args = parser.parse_args()
+
+    if args.content is None and args.content_file is None:
+        emit_error("Provide --content or --content-file.")
+    content = args.content if args.content is not None else Path(args.content_file).read_text(encoding="utf-8")
+
+    allow = load_allowlist()
+    cfg = load_config(require_token=False)
+    name = resolve_project(cfg, args.project)
+    gate_writes(allow, name)
+
+    root = project_dir(cfg, name)
+    if not root.is_dir():
+        emit_error(f"Project folder not found: {root} — create the project first (ignition_project_create).")
+
+    target = safe_join(root, args.path)
+    rel = target.relative_to(root).as_posix()
+
+    # Forbidden targets
+    parts = rel.split("/")
+    if any(p == ".resources" for p in parts):
+        emit_error(f"{rel}: .resources/ folders are gateway-internal — never write them.")
+    if target.name.endswith(".digest.json"):
+        emit_error(f"{rel}: digest files are gateway-managed — never write them.")
+    if parts[0] in ("config", "var"):
+        emit_error(f"{rel}: gateway config/var is out of scope for project writes.")
+    if target.name in FORBIDDEN_NAMES or target.suffix.lower() in FORBIDDEN_SUFFIXES:
+        emit_error(
+            f"{rel}: binary/managed files (images, .bin, thumbnails) are produced by the "
+            "gateway/Designer — write the text payload instead."
+        )
+
+    # JSON must parse (protects the gateway scan from bad files)
+    if target.suffix == ".json":
+        try:
+            json.loads(content)
+        except (json.JSONDecodeError, ValueError) as e:
+            emit_error(f"Refusing to write invalid JSON to {rel}: {e}")
+
+    # resource.json policy: only scaffold NEW resource folders; never edit existing
+    writing_resource_json = target.name == "resource.json"
+    if writing_resource_json and target.exists():
+        emit_error(
+            f"{rel} already exists — the gateway owns resource.json (signatures/timestamps). "
+            "Write the payload files instead; the scan updates attributes itself."
+        )
+
+    created_resource_json = False
+    if writing_resource_json:
+        created_resource_json = True
+
+    target.parent.mkdir(parents=True, exist_ok=True)
+
+    # Atomic write
+    existed = target.exists()
+    tmp = target.with_suffix(target.suffix + ".sylo-tmp")
+    tmp.write_text(content, encoding="utf-8", newline="\n")
+    tmp.replace(target)
+
+    # Resource-folder bookkeeping
+    scaffolded = False
+    files_list_updated = False
+    if not created_resource_json and target.parent != root:
+        res_meta = target.parent / "resource.json"
+        if not res_meta.exists():
+            files = sorted({p.name for p in target.parent.iterdir() if p.name != "resource.json"})
+            sig = hashlib.sha256(content.encode("utf-8")).hexdigest()
+            meta = {
+                "scope": "G",
+                "version": 1,
+                "restricted": False,
+                "overridable": True,
+                "files": files,
+                "attributes": {
+                    "lastModificationSignature": sig,
+                    "lastModification": {
+                        "actor": "Sylo",
+                        "timestamp": datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ"),
+                    },
+                },
+            }
+            tmp2 = res_meta.with_suffix(".json.sylo-tmp")
+            tmp2.write_text(json.dumps(meta, indent=2) + "\n", encoding="utf-8", newline="\n")
+            tmp2.replace(res_meta)
+            scaffolded = True
+        else:
+            # Existing resource folder: keep the files[] list in sync (attributes
+            # stay gateway-owned — only the files array is touched).
+            try:
+                meta = json.loads(res_meta.read_text(encoding="utf-8"))
+                files = meta.get("files")
+                if isinstance(files, list) and target.name not in files:
+                    files.append(target.name)
+                    meta["files"] = sorted(files)
+                    tmp2 = res_meta.with_suffix(".json.sylo-tmp")
+                    tmp2.write_text(json.dumps(meta, indent=2) + "\n", encoding="utf-8", newline="\n")
+                    tmp2.replace(res_meta)
+                    files_list_updated = True
+            except (json.JSONDecodeError, OSError):
+                pass  # malformed meta — the scan will flag it
+
+    emit(
+        {
+            "ok": True,
+            "project": name,
+            "path": rel,
+            "abs_path": str(target),
+            "bytes": len(content.encode("utf-8")),
+            "created": not existed,
+            "resource_json_scaffolded": scaffolded,
+            "resource_files_list_updated": files_list_updated,
+            "next": (
+                "Run ignition_validate (optional) then ignition_scan to hot-apply, "
+                "then ignition_screenshot to verify."
+            ),
+        }
+    )
+
+
+def safe_join(root: Path, rel: str) -> Path:
+    rel_clean = rel.replace("\\", "/").strip("/")
+    if not rel_clean:
+        emit_error("Empty path.")
+    if any(part == ".." for part in rel_clean.split("/")) or ":" in rel_clean:
+        emit_error(f"Illegal path: {rel!r}")
+    target = (root / rel_clean).resolve()
+    try:
+        target.relative_to(root.resolve())
+    except ValueError:
+        emit_error(f"Path escapes project root: {rel!r}")
+    return target
+
+
+if __name__ == "__main__":
+    main()

package/scripts/scan.py

@@ -0,0 +1,85 @@
+#!/usr/bin/env python3
+"""Trigger a gateway scan (hot-apply of on-disk edits), for ignition_scan tool.
+
+GATED by the write-allowlist (allow_scan). Protocol:
+  1. Check open Designer sessions — warn loudly if any (unsaved-edit risk)
+  2. Try to acquire the project scan lock (mutual exclusion with other scanners)
+  3. POST /data/api/v1/scan/{scope}  →  poll GET until the scan completes
+"""
+
+from __future__ import annotations
+
+import argparse
+import time
+from typing import Any
+
+from _allowlist import gate_scan, load_allowlist
+from _ignition import api, api_expect, load_config
+from _json_out import emit, emit_error
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--scope", choices=("projects", "config"), default="projects")
+    parser.add_argument("--wait", type=float, default=60.0, help="max seconds to poll for scan completion")
+    parser.add_argument("--no-lock", action="store_true", help="skip the scan-lock acquire attempt")
+    args = parser.parse_args()
+
+    allow = load_allowlist()
+    gate_scan(allow)
+    cfg = load_config()
+
+    out: dict[str, Any] = {"ok": True, "scope": args.scope}
+
+    # Designer conflict warning
+    status, designers, _ = api(cfg, "/data/api/v1/designers", timeout=10)
+    open_projects: list[str] = []
+    if status == 200 and isinstance(designers, list):
+        for s in designers:
+            if isinstance(s, dict):
+                open_projects.append(str(s.get("projectName") or s.get("project") or s.get("id") or "unknown"))
+    out["designer_sessions_open"] = open_projects
+    if open_projects and args.scope == "projects":
+        out["designer_warning"] = (
+            f"Designer is OPEN on: {', '.join(open_projects)}. If there are unsaved edits, "
+            "this scan may cause conflicts. Ask the operator to save/close first, or proceed only "
+            "if the operator confirms."
+        )
+
+    # Scan lock (best-effort; gateway rejects if already held)
+    if not args.no_lock and args.scope == "projects":
+        status, lock, _ = api(cfg, "/data/api/v1/scan-lock/projects", method="POST", body={}, timeout=10)
+        if status == 200:
+            out["scan_lock_acquired"] = True
+        elif status == 409:
+            out["scan_lock_acquired"] = False
+            out["scan_lock_note"] = "Lock held elsewhere — another scan in progress or Designer-locked."
+        else:
+            out["scan_lock_acquired"] = False
+            out["scan_lock_note"] = f"Lock acquire returned HTTP {status} (continuing without lock)."
+
+    # Trigger
+    api_expect(cfg, f"/data/api/v1/scan/{args.scope}", method="POST", timeout=30, what="scan trigger")
+    out["scan_triggered"] = True
+
+    # Poll
+    deadline = time.time() + args.wait
+    final: dict[str, Any] = {}
+    while time.time() < deadline:
+        status, st, _ = api(cfg, f"/data/api/v1/scan/{args.scope}", timeout=10)
+        if status == 200 and isinstance(st, dict):
+            final = st
+            if not st.get("scanActive", False):
+                break
+        time.sleep(1.0)
+    out["scan_status"] = final or "poll timed out — check ignition_gateway_logs"
+    out["completed"] = bool(final and not final.get("scanActive", False))
+    out["next"] = (
+        "Verify in the Designer / browser session, or ignition_screenshot for visual check. "
+        "If the resource did not appear, check ignition_gateway_logs for scan errors."
+    )
+    emit(out)
+
+
+if __name__ == "__main__":
+    main()

package/scripts/screenshot.py

@@ -0,0 +1,96 @@
+#!/usr/bin/env python3
+"""Screenshot a Perspective session with Playwright — ignition_screenshot.
+
+Uses the installed Chrome or Edge via Playwright channels (no browser
+download); falls back to bundled Chromium if present. Output PNG is saved to
+~/.ignition-sylo/screenshots/ by default — read it back with the analyze_image
+tool for vision critique (the design-quality loop).
+"""
+
+from __future__ import annotations
+
+import argparse
+from datetime import datetime
+from pathlib import Path
+from typing import Any
+
+from _ignition import load_config
+from _json_out import emit, emit_error
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--project", default="")
+    parser.add_argument("--path", default="", help="view path segment appended to the client URL (optional)")
+    parser.add_argument("--out", default="", help="output PNG path (default ~/.ignition-sylo/screenshots/...)")
+    parser.add_argument("--width", type=int, default=1600)
+    parser.add_argument("--height", type=int, default=900)
+    parser.add_argument("--wait-ms", type=int, default=9000, help="render settle time before capture")
+    parser.add_argument("--url", default="", help="full override URL (advanced)")
+    args = parser.parse_args()
+
+    try:
+        from playwright.sync_api import sync_playwright
+    except ImportError:
+        emit_error(
+            "playwright is not installed. pip install playwright  "
+            "(browsers not required — this tool uses installed Chrome/Edge). "
+            "Then retry."
+        )
+
+    cfg = load_config(require_token=False)
+    base = cfg["gateway_url"]
+    project = (args.project or cfg.get("default_project") or "").strip()
+    if not args.url and not project:
+        emit_error("No --url and no project (pass --project or set default_project).")
+
+    url = args.url or f"{base}/data/perspective/client/{project}"
+    if args.path:
+        url = url.rstrip("/") + "/" + args.path.strip("/")
+    out_path = (
+        Path(args.out).expanduser()
+        if args.out.strip()
+        else Path.home() / ".ignition-sylo" / "screenshots" / f"{project or 'session'}-{datetime.now().strftime('%Y%m%d-%H%M%S')}.png"
+    )
+    out_path.parent.mkdir(parents=True, exist_ok=True)
+
+    last_error = ""
+    with sync_playwright() as p:
+        browser = None
+        for channel in ("chrome", "msedge", None):
+            try:
+                # --no-proxy-server: headless verifier always targets the local
+                # gateway; a system/env proxy would block 127.0.0.1/localhost
+                # (observed live: Edge hung on goto until this arg was added).
+                browser = p.chromium.launch(channel=channel, headless=True, args=["--no-proxy-server"]) if channel else p.chromium.launch(headless=True, args=["--no-proxy-server"])
+                break
+            except Exception as e:  # noqa: BLE001 — try next channel
+                last_error = str(e)
+        if browser is None:
+            emit_error(f"Could not launch a browser: {last_error}")
+        page = browser.new_page(viewport={"width": args.width, "height": args.height})
+        page.goto(url, wait_until="domcontentloaded", timeout=30_000)
+        # Perspective is a websocket SPA: give it time to mount views
+        try:
+            page.wait_for_load_state("networkidle", timeout=args.wait_ms)
+        except Exception:  # noqa: BLE001 — settle-time exceeded, capture anyway
+            pass
+        page.wait_for_timeout(1500)
+        page.screenshot(path=str(out_path), full_page=False)
+        browser.close()
+
+    emit(
+        {
+            "ok": True,
+            "url": url,
+            "screenshot": str(out_path),
+            "operator_chat": (
+                f"Session screenshot saved: {out_path}. Read it with analyze_image to critique "
+                "layout/spacing/hierarchy, then iterate (edit → scan → re-screenshot)."
+            ),
+        }
+    )
+
+
+if __name__ == "__main__":
+    main()

package/scripts/status.py

@@ -0,0 +1,91 @@
+#!/usr/bin/env python3
+"""Gateway + config + allowlist status for ignition_status tool."""
+
+from __future__ import annotations
+
+import time
+from typing import Any
+
+from _allowlist import load_allowlist, summary
+from _ignition import api, load_config, mask_token, projects_dir
+from _json_out import emit
+
+
+def main() -> None:
+    cfg = load_config(require_token=False)
+    allow = load_allowlist()
+    out: dict[str, Any] = {
+        "ok": True,
+        "config_path": cfg["_config_path"],
+        "gateway_url": cfg["gateway_url"],
+        "api_token_set": bool(cfg.get("api_token")),
+        "api_token_hint": mask_token(cfg.get("api_token", "")),
+        "data_dir": cfg.get("data_dir"),
+        "default_project": cfg.get("default_project"),
+        "data_dir_exists": bool(cfg.get("data_dir")) and projects_dir(cfg).parent.is_dir(),
+        "allowlist": summary(allow),
+    }
+
+    # Gateway reachability + identity
+    status, info, _ = api(cfg, "/data/api/v1/gateway-info", timeout=10)
+    out["gateway_reachable"] = status == 200
+    if status == 200 and isinstance(info, dict):
+        out["gateway"] = {
+            "version": info.get("ignitionVersion"),
+            "edition": info.get("edition"),
+            "deployment_mode": info.get("deploymentMode"),
+            "hostname": info.get("hostname"),
+            "jvm": info.get("jvmVersion"),
+            "redundancy_role": info.get("redundancyRole"),
+        }
+        out["gateway"] = {k: v for k, v in out["gateway"].items() if v is not None}
+    elif status in (401, 403):
+        out["auth_problem"] = (
+            f"gateway-info returned HTTP {status}. "
+            + (
+                "Token missing — create an API key and put it in config."
+                if status == 401
+                else "Token lacks permission — assign the key a custom security level granted "
+                "Gateway Read+Write (Platform > Security > General Settings > Roles and Permissions)."
+            )
+        )
+
+    # Projects
+    status, projects, _ = api(cfg, "/data/api/v1/projects/list", timeout=10)
+    if status == 200 and isinstance(projects, list):
+        out["projects"] = [
+            {
+                "name": p.get("name"),
+                "title": p.get("title"),
+                "enabled": p.get("enabled"),
+                "writable_by_agent": p.get("name") in (out["allowlist"]["writable_projects"] or []),
+            }
+            for p in projects
+            if isinstance(p, dict)
+        ]
+
+    # Open Designer sessions (conflict warning for file writes / scans)
+    designers: list[str] = []
+    status, dsessions, _ = api(cfg, "/data/api/v1/designers", timeout=10)
+    if status == 200 and isinstance(dsessions, list):
+        for s in dsessions:
+            if isinstance(s, dict):
+                designers.append(str(s.get("projectName") or s.get("project") or s.get("id") or "unknown"))
+    out["designer_sessions_open"] = designers
+    if designers:
+        out["operator_chat"] = (
+            f"⚠️ Designer is open on: {', '.join(designers)}. Save or close those projects before "
+            "scanning — a scan while the Designer has unsaved edits can conflict. Read-only work is fine."
+        )
+    else:
+        out["operator_chat"] = (
+            "Ignition gateway online — file-based 8.3 workflow ready. Typical flow: "
+            "ignition_project_resources → ignition_resource_read → edit → ignition_resource_write → "
+            "ignition_scan → ignition_screenshot to verify. Writes are gated by the allowlist: "
+            f"writable projects = {out['allowlist']['writable_projects'] or 'none'}."
+        )
+    emit(out)
+
+
+if __name__ == "__main__":
+    main()