sylo-ignition 0.1.0

package/scripts/validate.py

@@ -0,0 +1,252 @@
+#!/usr/bin/env python3
+"""Offline lint/validate of a project resource before scanning.
+
+For ignition_validate tool. Heuristic (no vendor SDK):
+  - view.json: structure, unique meta.name, known component types, binding shapes
+  - resource.json: required keys
+  - .py (project scripts): Jython 2.7 compatibility (f-strings etc. are errors)
+  - tag JSON: light structure check
+Errors block the write; warnings are advisory. This tool never calls the gateway.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import re
+from pathlib import Path
+from typing import Any
+
+from _ignition import load_config, project_dir, resolve_project
+from _json_out import emit, emit_error
+
+KNOWN_VIEW_TYPES = {
+    "ia.display.label",
+    "ia.display.led",
+    "ia.display.multistate-indicator",
+    "ia.display.table",
+    "ia.display.path",
+    "ia.shapes.svg",
+    "ia.input.btn",
+    "ia.input.dropdown",
+    "ia.input.numeric-entry",
+    "ia.input.text-field",
+    "ia.input.slider",
+    "ia.input.toggle-switch",
+    "ia.input.checkbox",
+    "ia.container.flex",
+    "ia.container.column",
+    "ia.container.row",
+    "ia.container.coord",
+    "ia.container.tabs",
+    "ia.container.accordian",
+    "ia.container.dropdown-menu",
+    "ia.container.menus",
+    "ia.container.modal",
+    "ia.container.popup",
+    "ia.container.split",
+    "ia.container.tab-container",
+    "ia.container.template",
+    "ia.chart.xy-chart",
+    "ia.powerchart.powerchart",
+    "ia.gauge.led-numeric-entry",
+    "ia.gauge.linear-gauge",
+    "ia.gauge.radial-gauge",
+    "ia.gauge.arc",
+    "ia.alarm.journal-table",
+    "ia.alarm.status-table",
+    "ia.logos.inductive-automation",
+    "ia.display.image",
+    "ia.display.markdown",
+    "ia.embedded.websocket",
+    "ia.embedded.video",
+    "ia.barcode.qrcode",
+    "ia.tagtags.tag-canvas",
+    "em.charts.chartjs",
+}
+BINDING_TYPES = {"property", "tag", "expr", "query", "tagHistory", "propertyBinding", "exprBinding", "tagBinding"}
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--project", default="")
+    parser.add_argument("--path", required=True)
+    args = parser.parse_args()
+
+    cfg = load_config(require_token=False)
+    name = resolve_project(cfg, args.project)
+    root = project_dir(cfg, name)
+    target = (root / args.path.replace("\\", "/").strip("/")).resolve()
+    if not target.is_file():
+        emit_error(f"Not found: {args.path} (in {root})")
+
+    errors: list[str] = []
+    warnings: list[str] = []
+    checks: list[str] = []
+
+    raw = target.read_text(encoding="utf-8", errors="replace")
+
+    if target.name == "view.json":
+        validate_view(raw, errors, warnings, checks)
+    elif target.name == "resource.json":
+        validate_resource_json(raw, errors, warnings, checks)
+    elif target.suffix == ".py":
+        validate_jython(raw, errors, warnings, checks)
+    elif target.suffix == ".json":
+        checks.append("generic JSON parse")
+        try:
+            json.loads(raw)
+        except (json.JSONDecodeError, ValueError) as e:
+            errors.append(f"invalid JSON: {e}")
+    else:
+        checks.append("no validation rules for this file type — skipped")
+
+    emit(
+        {
+            "ok": len(errors) == 0,
+            "project": name,
+            "path": args.path,
+            "errors": errors,
+            "warnings": warnings,
+            "checks_run": checks,
+        }
+    )
+
+
+# ---- view.json ----------------------------------------------------------------
+
+def validate_view(raw: str, errors: list[str], warnings: list[str], checks: list[str]) -> None:
+    checks.append("view.json: JSON parse")
+    try:
+        view = json.loads(raw)
+    except (json.JSONDecodeError, ValueError) as e:
+        errors.append(f"view.json is not valid JSON: {e}")
+        return
+    if not isinstance(view, dict):
+        errors.append("view.json root must be an object")
+        return
+    checks.append("view.json: root component (verified 8.3.9 shape)")
+
+    # VERIFIED structure (live 8.3.9): top-level "root" is the root COMPONENT
+    # (e.g. ia.container.coord) with children — NOT props.root.children.
+    # A malformed view is silently dropped by the scan.
+    root = view.get("root")
+    if not isinstance(root, dict):
+        errors.append(
+            'view.json must have a top-level "root" component object '
+            '(e.g. {"type": "ia.container.coord", "meta": {"name": "root"}, "children": [...]})'
+        )
+        return
+    if root.get("type") not in ("ia.container.coord", "ia.container.flex", "ia.container.column", "ia.container.row"):
+        errors.append(f'root.type should be a container type, got {root.get("type")!r}')
+    if not isinstance(root.get("children"), list):
+        warnings.append("root.children missing or not a list — empty view?")
+
+    names: list[str] = []
+    depth_violations: list[str] = []
+    count = 0
+    percent_mode_nodes: list[str] = []
+
+    def walk(node: Any, path: str, depth: int) -> None:
+        nonlocal count
+        if not isinstance(node, dict):
+            return
+        count += 1
+        ctype = node.get("type", "")
+        if isinstance(ctype, str) and ctype and ctype not in KNOWN_VIEW_TYPES and not ctype.startswith("ia."):
+            warnings.append(f"unknown component type {ctype!r} at {path}")
+        meta = node.get("meta", {})
+        nm = meta.get("name") if isinstance(meta, dict) else None
+        if nm:
+            if nm in names:
+                errors.append(f"duplicate meta.name {nm!r} at {path} — names must be unique")
+            names.append(nm)
+        pos = node.get("position")
+        if isinstance(pos, dict) and pos.get("mode") == "percent":
+            percent_mode_nodes.append(path)
+        if depth > 12:
+            depth_violations.append(path)
+        for child in node.get("children", []) or []:
+            walk(child, f"{path}/{nm or ctype}", depth + 1)
+
+    for child in root.get("children") or []:
+        walk(child, "<root>", 1)
+    checks.append(f"view.json: {count} components, {len(names)} named")
+
+    if depth_violations:
+        warnings.append(f"deep nesting (>12) at: {', '.join(depth_violations[:5])}")
+    if count > 300:
+        warnings.append(f"{count} components — very heavy view; consider templates/splitting")
+    if percent_mode_nodes:
+        warnings.append(
+            "position.mode 'percent' observed but UNVERIFIED on 8.3.9 (labels stacked at 0,0 in "
+            "live testing — use absolute px inside coord containers until verified)"
+        )
+
+    # Binding shape check: any {binding: {...}} must have a known type
+    bind_re = re.compile(r'"binding"\s*:\s*\{')
+    if bind_re.search(raw):
+        checks.append("view.json: binding objects present — verifying types")
+        bad = find_bad_bindings(view)
+        for b in bad:
+            errors.append(f"binding without a known 'type' at {b}")
+
+    # Perspective expression binding syntax quick check
+    for m in re.finditer(r"\{([^{}\n]{1,200})\}", raw):
+        expr = m.group(1)
+        if re.search(r"\bf\"|f'", expr):
+            warnings.append(f"possible f-string in expression {expr[:60]!r} — Perspective expressions are not Python")
+
+
+def find_bad_bindings(node: Any, path: str = "") -> list[str]:
+    bad: list[str] = []
+    if isinstance(node, dict):
+        if set(node.keys()) == {"binding"} or "binding" in node:
+            b = node.get("binding")
+            if isinstance(b, dict) and b.get("type") not in BINDING_TYPES:
+                bad.append(path or "<root>")
+        for k, v in node.items():
+            bad.extend(find_bad_bindings(v, f"{path}/{k}"))
+    elif isinstance(node, list):
+        for i, v in enumerate(node):
+            bad.extend(find_bad_bindings(v, f"{path}[{i}]"))
+    return bad
+
+
+# ---- resource.json ------------------------------------------------------------
+
+def validate_resource_json(raw: str, errors: list[str], warnings: list[str], checks: list[str]) -> None:
+    checks.append("resource.json: keys")
+    try:
+        meta = json.loads(raw)
+    except (json.JSONDecodeError, ValueError) as e:
+        errors.append(f"resource.json is not valid JSON: {e}")
+        return
+    for key in ("scope", "version", "files"):
+        if key not in meta:
+            errors.append(f"resource.json missing key: {key}")
+    if meta.get("scope") != "G":
+        errors.append("resource.json scope must be 'G'")
+
+
+# ---- Jython 2.7 ---------------------------------------------------------------
+
+def validate_jython(raw: str, errors: list[str], warnings: list[str], checks: list[str]) -> None:
+    checks.append("python: Jython 2.7 compatibility")
+    for i, line in enumerate(raw.splitlines(), 1):
+        if re.search(r"\bf['\"]", line):
+            errors.append(f"line {i}: f-string — Jython 2.7 has no f-strings; use .format() or %")
+        if re.search(r"\basync\s+def\b|\bawait\b", line):
+            errors.append(f"line {i}: async/await — not available in Jython 2.7")
+        if ":=" in line and not line.strip().startswith("#"):
+            warnings.append(f"line {i}: walrus ':=' — not available in Jython 2.7")
+        if re.match(r"\s*print\s+[^(\s]", line) and "#" not in line.split("print")[0]:
+            warnings.append(f"line {i}: print statement without parens (works in 2.7, not Python 3)")
+        if re.search(r"\bmatch\s+\w+.*:$", line.strip()) and "case" in raw:
+            warnings.append(f"line {i}: 'match' statement — Jython 2.7 has no structural pattern matching")
+    if re.search(r"^\s*import\s+(dataclasses|typing\.extensions|pathlib)\b", raw, re.M):
+        warnings.append("import of a Python-3-only stdlib module (dataclasses/typing.extensions/pathlib) — unavailable in Jython 2.7")
+
+
+if __name__ == "__main__":
+    main()

package/skills/ignition/SKILL.md

@@ -0,0 +1,131 @@
+---
+name: ignition
+description: Create and edit Ignition 8.3 projects — file-based resource authoring on the gateway's data dir, REST scan to hot-apply, screenshot-verified Perspective UI. Write-allowlist gated; 8.1 is NOT supported.
+metadata:
+  sylo:
+    category: automation
+    icon: cpu
+---
+
+# Ignition — file-based 8.3 workflow
+
+Sylo edits Ignition **8.3** project resources directly on disk (`data/projects/<name>/...`),
+then triggers a gateway **scan** to hot-apply them — no Designer import step, no zip. All
+mutating tools enforce the operator-managed **write-allowlist**. This targets **8.3 only**:
+8.1 keeps projects + config in an internal SQLite DB with no REST API — see the reference
+skill's version notes.
+
+## First-run setup (operator, one time)
+
+1. **API key**: gateway web UI → Platform → Security → API Keys → Create API Key +
+   (Basic Token). Uncheck "Require secure connections" for a plain-HTTP local gateway.
+   Copy the token.
+2. **Security level**: Platform → Security → **Levels** → select `Authenticated` →
+   Add Level + → name it `SyloAPI` → Save. Then edit the API key and check `SyloAPI`.
+   (Role-derived levels like Administrator are greyed out for API keys — custom levels are not.)
+3. **Grant access**: Platform → Security → General Settings → **Roles and Permissions** →
+   check `SyloAPI` for Gateway Read AND Gateway Write. Save.
+4. **Config file** at `C:\Users\<user>\.ignition-sylo\config.json` (OUTSIDE any repo —
+   tokens never go in git):
+   ```json
+   {
+     "gateway_url": "http://localhost:8088",
+     "api_token": "Sylo:...",
+     "data_dir": "C:\\Program Files\\Inductive Automation\\Ignition\\data",
+     "default_project": "SyloSandbox"
+   }
+   ```
+5. **File-write permission** (native Windows install under Program Files — one time,
+   elevated PowerShell; the Users group only has read on the data dir by default):
+   ```powershell
+   icacls "C:\Program Files\Inductive Automation\Ignition\data\projects" /grant "<user>:(OI)(CI)M"
+   icacls "C:\Program Files\Inductive Automation\Ignition\data\config" /grant "<user>:(OI)(CI)M"
+   ```
+6. `ignition_status` should now show `gateway_reachable: true` and the project list.
+
+## Core loop
+
+1. **`ignition_status`** — always first. Note open Designer sessions (conflict risk),
+   which projects exist, and what the allowlist permits.
+2. **`ignition_project_resources`** — see the resource tree of the project you'll touch.
+3. **`ignition_resource_read`** — study existing views before authoring (match the
+   house style; the Example project's `mainView` is a good reference).
+4. Author/edit → **`ignition_validate`** (catch structure + Jython-2.7 errors offline).
+5. **`ignition_resource_write`** — allowlist-gated atomic write. New folders get a
+   scan-compatible `resource.json` scaffold automatically.
+6. **`ignition_scan`** (scope projects) — hot-apply into the gateway + Designer.
+7. **`ignition_screenshot`** → `analyze_image` — visual verification / design critique loop.
+8. If something didn't apply: **`ignition_gateway_logs`** (search "scan" / "resource").
+
+Use **`ignition_project_create`** for a scratch project, and **`ignition_backup`**
+before risky or bulk changes (restorable .gwbk in `~/.ignition-sylo/backups/`).
+**`ignition_api_get`** is the read-only passthrough for everything else on the
+588-route API (resource lists, sessions, tag export JSON, gateway info...).
+
+## Gates (hard rules)
+
+| Tool | Gate |
+|------|------|
+| `ignition_resource_write` | project must be present + **enabled** in `assets/write-allowlist.json` |
+| `ignition_scan` | `allow_scan` must be true |
+| `ignition_project_create` | `allow_project_create` must be true (creates only NEW isolated projects) |
+| write-allowlist itself | **never edit it as the agent** — operator-owned; ask the operator |
+
+If a gate blocks you, explain to the operator exactly what to change and stop.
+Default scratch project: **SyloSandbox** (pre-enabled). Never write `Example`
+(read-only by default) or any production project the operator hasn't listed.
+
+## Forbidden paths (the write tool also refuses these)
+
+- `**/.resources/`, `*.digest.json` — gateway internals
+- `data/var/**`, `config/local/**`, `*.idb` — runtime state / local overrides
+- `*.bin`, thumbnails, images — binary payloads produced by Designer/gateway
+- Existing `resource.json` — the gateway owns it (signatures/timestamps);
+  new-resource scaffolds are created automatically by the write tool
+- Gateway `data/config/**` — out of scope for project writes (Phase 3)
+
+## Designer conflict rule
+
+A scan while the Designer has **unsaved edits** can clobber them. Before
+`ignition_scan`, check `ignition_status`. If Designer sessions are open, ask the
+operator to save/close (or confirm proceed). Never scan silently over an open
+Designer.
+
+## Gotchas
+
+- **Views are reachable only via pages**: a new project has no page-config, so sessions
+  show "No view configured for this page". Write
+  `com.inductiveautomation.perspective/page-config/config.json` mapping `"/"` to your
+  view path (schema in the reference skill), then scan. The URL after the project name
+  is the PAGE path, not the view path.
+- **The scan silently drops malformed resources** — a bad view.json produces no error,
+  just an absent view. ALWAYS screenshot-verify after scanning; if the view is missing,
+  check the structure against the verified schema (top-level `root` component — see
+  reference skill) and `ignition_gateway_logs`.
+- **Position modes**: `flow` inside flex containers is verified working; **`percent`
+  inside coord containers did NOT apply in live testing** (labels stacked at 0,0) — use
+  absolute pixel x/y/width/height inside coord containers.
+- **Jython 2.7**: project gateway scripts are Python 2 — no f-strings, no
+  async/await, no pathlib. `ignition_validate` catches these; write `.format()` code.
+- **Windows paths**: resource paths use forward slashes in tool calls; the
+  scripts handle OS joins. Keep view folder names short (255-char path limit).
+- **Program Files ACL**: native installs need the one-time icacls grant (setup step 5)
+  — otherwise writes fail with Access denied.
+- **Encoding**: scripts run with UTF-8 forced; write tool always writes UTF-8
+  with `\n` endings.
+- **Scans are global**: `scan/projects` scans ALL projects, not just yours —
+  another reason the Designer rule matters.
+- **No tag VALUES via REST**: 8.3 REST manages tag *definitions* (tags export/import
+  JSON); live values go through scripting/OPC-UA — currently out of scope.
+- The full offline 8.3 User Manual (1,566 pages) + SDK docs live in the Sylo repo at
+  `packages/sylo-ignition/references/` — grep them via the **ignition-reference** skill
+  before guessing formats.
+
+## Design quality (operator standard: beautiful, intuitive, clean)
+
+When building views, aim for real design quality, not just function: consistent
+spacing rhythm, meaningful hierarchy (page title → section → content), color used
+sparingly for state (not decoration), labels that read like the machine ("Conveyor
+Speed" not "tag1"), large readable values for at-a-glance operation. Always
+screenshot and critique against these rules before reporting done; iterate at
+least once when something feels off.

package/skills/ignition-reference/SKILL.md

@@ -0,0 +1,157 @@
+---
+name: ignition-reference
+description: Ignition 8.3 offline documentation map + format quickrefs — Perspective view JSON, bindings, component catalog, tag JSON, theme files, gateway REST routes, Jython 2.7. Grep the local manual before guessing.
+metadata:
+  sylo:
+    category: automation
+    icon: cpu
+---
+
+# Ignition reference — offline docs + format quickrefs
+
+## Offline documentation (grep here first)
+
+Full 8.3 User Manual as grep-friendly Markdown (1,566 pages) + SDK guide live in the
+Sylo repo:
+
+- `packages/sylo-ignition/references/user-manual-8.3/` — the whole manual, Docusaurus
+  pages converted to `.md` (pipe/grid tables, fenced code, internal links rewritten
+  to relative `.md`). `references/README.md` lists key pages.
+- `packages/sylo-ignition/references/sdk-docs/` — SDK Programmer's Guide (resource
+  collections, module model).
+- `packages/sylo-ignition/references/user-manual-8.1-pdfs/` — official 8.1 PDFs
+  (git-ignored, 262 MB; 8.1 has NO REST API / file config — only zip + gwbk workflows).
+- `packages/sylo-ignition/references/gateway-rest-api-8.3.md` — verified route map of
+  the 588-route REST API + the working API-key auth recipe.
+- Regenerate everything: `python packages/sylo-ignition/scripts/fetch_docs.py`.
+
+Key manual pages (relative to `user-manual-8.3/`):
+
+- Perspective components: `appendix/components/perspective-components/` (every
+  component: props, events, style tips)
+- Perspective props/bindings: `perspective/props/` and `perspective/bindings/`
+- Expressions: `appendix/expression-functions/` ( Perspective expression language)
+- Scripting (Jython 2.7): `appendix/scripting-functions/` + `perspective/scripting/`
+- Tags: `platform/tags/` (tag properties, UDTs, tag file JSON)
+- Gateway folder structure: `appendix/reference-pages/gateway-folder-structure.md`
+- Version control / file-based config: `tutorials/version-control-guide.md`
+- Security: `platform/security/` (API keys, security levels, zones)
+
+## On-disk layout (8.3, verified on a live gateway)
+
+```
+data/
+├── projects/<Name>/
+│   ├── project.json               # {title, description, enabled, inheritable, parent}
+│   └── com.inductiveautomation.perspective/
+│       ├── views/<viewPath>/     # view.json + thumbnail.png + resource.json
+│       ├── page-config/config.json/
+│       ├── page-startup/onPageStartup.py/
+│       └── session-props/props.json/
+└── config/                        # gateway config (JSON, scan via /scan/config)
+```
+
+`resource.json` (per folder, gateway-owned — never hand-edit existing):
+`{scope: "G", version: 1, restricted, overridable, files: [...], attributes:
+{lastModificationSignature, lastModification: {actor, timestamp}}}`
+
+## Perspective view.json quickref (VERIFIED live on 8.3.9)
+
+```json
+{
+  "custom": {},
+  "params": {},
+  "props": {},
+  "root": {
+    "type": "ia.container.coord",
+    "meta": { "name": "root" },
+    "children": [
+      {
+        "type": "ia.display.label",
+        "meta": { "name": "titleLabel" },
+        "position": { "x": 24, "y": 24, "width": 400, "height": 40 },
+        "props": {
+          "text": "Machine Overview",
+          "style": { "fontSize": "24px", "fontWeight": "bold" }
+        }
+      }
+    ]
+  }
+}
+```
+
+- **`root` is a top-level key holding the root COMPONENT** (usually
+  `ia.container.coord`) — NOT `props.root.children`. Malformed views are
+  silently dropped by the scan.
+- Component `type` comes from the catalog (`ia.<family>.<component>`); full prop
+  details in `appendix/components/perspective-components/`.
+- `meta.name` must be **unique** across the view.
+- Position: absolute px (`x`,`y`,`width`,`height`) inside coord containers — VERIFIED.
+  `mode: "flow"` for children of flex containers — VERIFIED. `mode: "percent"` —
+  did NOT apply in live testing (unverified; avoid for now).
+- Style lives under `props.style` (CSS-ish: fontSize, backgroundColor, padding,
+  width, height); shared looks go in **style classes** (manual: `perspective/style-classes/`),
+  referenced via `props.style.classes`.
+
+## Page-config quickref (VERIFIED live on 8.3.9)
+
+`com.inductiveautomation.perspective/page-config/config.json` — without it,
+sessions show "No view configured for this page":
+
+```json
+{
+  "pages": {
+    "/": { "viewPath": "Home" },
+    "/alarms": { "viewPath": "Alarms/Console" }
+  },
+  "sharedDocks": { "cornerPriority": "top-bottom" }
+}
+```
+
+URL `…/data/perspective/client/<project>/<page>` maps `page` to the pages key above
+(root page = `/`).
+
+## Bindings quickref
+
+Property bindings wrap the value:
+
+```json
+"props": { "text": { "binding": { "type": "property", "config": { "path": "view.params.title" } } } }
+```
+
+- `type: "property"` → `config.path` (`view.x`, `self.x`, `session.props.x`)
+- `type: "tag"` → `config.path: "[default]Line1/Speed"`, optional `config.op` e.g.
+  `readBlocking`? (see manual `perspective/bindings/tag-binding.md` for transforms/format)
+- `type: "expr"` → `config.expression` — Perspective expression language
+  (`{view.params.speed} * 60`, `coalesce()`, `if()`, `toFix()`)
+- Transforms: `config.transforms: [{"type": "map", "config": {...}}]` etc.
+
+## Tag file JSON quickref
+
+Tags (definitions) live in the provider's config or can be round-tripped as JSON via
+`GET /data/api/v1/tags/export` / `POST /data/api/v1/tags/import`. UDT definitions,
+value types (`Int4`, `Float8`, `Boolean`, `String8`), alarm definitions — see
+`platform/tags/tag-properties.md` and `platform/tags/udts/`. REST manages
+definitions; live **values** need scripting/OPC-UA.
+
+## Jython 2.7 quickref (gateway scripts)
+
+Python 2 syntax: `print x` ok, prefer `print(x)`; string formatting `%` or
+`.format()`; no f-strings, no async, no pathlib/dataclasses/match. `system.*`
+scripting functions in `appendix/scripting-functions/` (e.g.
+`system.tag.readBlocking`, `system.perspective.sendMessage`).
+
+## Gateway REST quickref
+
+- Auth: header `X-Ignition-API-Token`; 401 = dead token, 403 = insufficient
+  security level (see gateway-rest-api-8.3.md for the working SyloAPI recipe)
+- Projects: `/data/api/v1/projects/{list,names,find/{n},copy,rename/{n},export/{n},import/{n}}`
+- Scan: `POST /data/api/v1/scan/{projects,config}`; lock:
+  `POST /data/api/v1/scan-lock/projects`
+- Resources (gateway config types incl. tag-provider, opcua device, perspective
+  themes): `/data/api/v1/resources/{list,names,find,singleton}/{moduleId}/{typeId}`
+- Tags: `/data/api/v1/tags/{export,import}` (JSON definitions)
+- Perspective: `/data/perspective/api/v1/sessions/`, `.../themes/copy-base-themes`
+- Status/diagnostics: `/data/api/v1/{gateway-info,overview,overview/problems,logs}`,
+  `GET /data/api/v1/backup` (.gwbk), `/data/api/v1/designers` (open sessions)
+- Full spec: `GET /openapi.json` (12 MB — save to disk, don't inline)