@synopackageland/templates 0.38.1 → 0.39.0

package/templates/native-node/examples/operations.json

@@ -0,0 +1,112 @@
+{
+  "format": "synopkgland.api",
+  "version": 2,
+  "operations": {
+    "example.read": {
+      "summary": "Read a resource",
+      "ai": "read",
+      "cli": [
+        "example",
+        "read"
+      ],
+      "effect": "read",
+      "permission": "administrators",
+      "paramsSchema": {
+        "type": "object",
+        "additionalProperties": false
+      },
+      "resultSchema": {
+        "type": "object"
+      },
+      "flow": {
+        "type": "invoke",
+        "method": "example.read"
+      }
+    },
+    "example.preview": {
+      "summary": "Preview a resource change",
+      "ai": "preview",
+      "cli": [
+        "example",
+        "preview"
+      ],
+      "effect": "read",
+      "permission": "administrators",
+      "paramsSchema": {
+        "type": "object",
+        "additionalProperties": false
+      },
+      "resultSchema": {
+        "type": "object"
+      },
+      "flow": {
+        "type": "invoke",
+        "method": "example.preview"
+      }
+    },
+    "example.draft": {
+      "summary": "Draft a resource change for human confirmation",
+      "ai": "draft",
+      "cli": [
+        "example",
+        "draft"
+      ],
+      "effect": "write",
+      "permission": "administrators",
+      "paramsSchema": {
+        "type": "object",
+        "additionalProperties": false
+      },
+      "resultSchema": {
+        "type": "object"
+      },
+      "flow": {
+        "type": "invoke",
+        "method": "example.draft"
+      },
+      "preview": "example.preview"
+    },
+    "example.human": {
+      "summary": "Delete a resource after human review",
+      "ai": "human-only",
+      "cli": [
+        "example",
+        "human"
+      ],
+      "effect": "destructive",
+      "permission": "administrators",
+      "paramsSchema": {
+        "type": "object",
+        "additionalProperties": false
+      },
+      "resultSchema": {
+        "type": "object"
+      },
+      "flow": {
+        "type": "invoke",
+        "method": "example.human"
+      }
+    },
+    "example.hidden": {
+      "summary": "Read internal state",
+      "ai": "hidden",
+      "cli": [
+        "example",
+        "hidden"
+      ],
+      "effect": "read",
+      "permission": "administrators",
+      "paramsSchema": {
+        "type": "object",
+        "additionalProperties": false
+      },
+      "resultSchema": {
+        "type": "object"
+      },
+      "flow": {
+        "type": "invoke",
+        "method": "example.hidden"
+      }
+    }
+  }
+}

package/templates/native-node/operations.json

@@ -0,0 +1,27 @@
+{
+  "format": "synopkgland.api",
+  "version": 2,
+  "operations": {
+    "app.status": {
+      "summary": "Read App status",
+      "ai": "read",
+      "cli": [
+        "app",
+        "status"
+      ],
+      "effect": "read",
+      "permission": "administrators",
+      "paramsSchema": {
+        "type": "object",
+        "additionalProperties": false
+      },
+      "resultSchema": {
+        "type": "object"
+      },
+      "flow": {
+        "type": "invoke",
+        "method": "app.status"
+      }
+    }
+  }
+}

package/templates/native-node-delegate/operations.patch.json

@@ -0,0 +1,20 @@
+{
+  "operations": {
+    "report.save": {
+      "summary": "Save an example report",
+      "ai": "hidden",
+      "effect": "write",
+      "permission": "authenticated",
+      "cli": [
+        "report",
+        "save"
+      ],
+      "paramsSchema": {},
+      "resultSchema": {},
+      "flow": {
+        "type": "invoke",
+        "method": "report.save"
+      }
+    }
+  }
+}

package/templates/native-node-jobs/operations.patch.json

@@ -0,0 +1,52 @@
+{
+  "operations": {
+    "hash.submit": {
+      "summary": "Start a file hash job",
+      "ai": "hidden",
+      "effect": "write",
+      "permission": "administrators",
+      "cli": [
+        "hash",
+        "submit"
+      ],
+      "paramsSchema": {},
+      "resultSchema": {},
+      "flow": {
+        "type": "invoke",
+        "method": "hash.submit"
+      }
+    },
+    "hash.get": {
+      "summary": "Read a file hash job",
+      "ai": "hidden",
+      "effect": "read",
+      "permission": "administrators",
+      "cli": [
+        "hash",
+        "get"
+      ],
+      "paramsSchema": {},
+      "resultSchema": {},
+      "flow": {
+        "type": "invoke",
+        "method": "hash.get"
+      }
+    },
+    "hash.cancel": {
+      "summary": "Cancel a file hash job",
+      "ai": "hidden",
+      "effect": "write",
+      "permission": "administrators",
+      "cli": [
+        "hash",
+        "cancel"
+      ],
+      "paramsSchema": {},
+      "resultSchema": {},
+      "flow": {
+        "type": "invoke",
+        "method": "hash.cancel"
+      }
+    }
+  }
+}

package/templates/native-node-root-ops/operations.patch.json

@@ -0,0 +1,20 @@
+{
+  "operations": {
+    "whoami.run": {
+      "summary": "Run the approved identity operation",
+      "ai": "hidden",
+      "effect": "write",
+      "permission": "administrators",
+      "cli": [
+        "whoami",
+        "run"
+      ],
+      "paramsSchema": {},
+      "resultSchema": {},
+      "flow": {
+        "type": "invoke",
+        "method": "whoami.run"
+      }
+    }
+  }
+}

package/templates/native-python/README.md

@@ -6,7 +6,7 @@ runs as its own DSM package account, needs no containers, and has no root by def
 
 ```text
 DSM main menu → DSM window (ui/app.js)
-                   │  ctx.call("greeting.get")  same-origin POST + DSM session
+                   │  ctx.call("app.status")  same-origin POST + DSM session
                    ▼
    /webman/3rdparty/__PACKAGE__/cgi/api.cgi   (the SDK runtime, runs as package user)
       1. transport guards: POST, JSON, same origin, ≤ 1 MiB, bounded JSON complexity
@@ -17,7 +17,7 @@ DSM main menu → DSM window (ui/app.js)
 
 ## Requests and long work
 
-SDK/App 0.43.0 defaults to 300-second requests and a 302-second browser wait.
+SDK/App 0.47.0 defaults to 300-second requests and a 302-second browser wait.
 Explicit `backend.timeout_seconds` and earlier parent deadlines still apply;
 rebuild the App to use the new SDK. For long NAS work, enable the existing jobs
 capability: return admission and the original job ID promptly, execute in the
@@ -27,7 +27,7 @@ last queued/running state intact. After a lost admission reply, reuse the same
 idempotency key and input instead of replaying a mutation with a new key.
 Jobs default to 30 minutes; approved executor limits remain separate. ctl keeps
 its 62-second transport default; use an explicit `--timeout` or an existing
-nonblocking job. See the SDK's [request deadline contract](https://github.com/synopackageland/syno-pkg-land-sdk/blob/v0.43.0/docs/request-deadlines.md).
+nonblocking job. See the SDK's [request deadline contract](https://github.com/synopackageland/syno-pkg-land-sdk/blob/v0.47.0/docs/request-deadlines.md).
 
 ## Quick start
 
@@ -35,6 +35,8 @@ Needs Node.js with `synopkgland` installed, and Python 3.8 or later.
 
 ```bash
 (cd backend && python3 -m unittest discover -s tests)   # method tests
+synopkgland ctl generate
+synopkgland check
 synopkgland build           # → dist/__PACKAGE__-0.1.0-0001-{x86_64,aarch64}.spk
 synopkgland inspect dist/__PACKAGE__-0.1.0-0001-x86_64.spk
 ```
@@ -42,8 +44,7 @@ synopkgland inspect dist/__PACKAGE__-0.1.0-0001-x86_64.spk
 Install: Package Center → Settings → General → Trust Level "Any publisher",
 then Manual Install with the SPK for your NAS's CPU. Open
 **__DISPLAY_NAME__** from the DSM main menu: it shows who you are signed in
-as, what the backend reports, and (for administrators) a form that stores a
-greeting in the package's data folder.
+as and what the backend reports.
 
 ## Project layout
 
@@ -55,7 +56,7 @@ greeting in the package's data folder.
 | `i18n/glossary.json` | DSM's own UI terms, and which messages must use them | Add terms |
 | `backend/app/routes.py` | Your methods: `build` registers them | Yes — your backend |
 | `backend/app/jobs.py`, `root_ops.py`, `delegate.py` | Capability examples (stubs unless `init --with` added them) | Yes |
-| `backend/app/permissions.json` | Who may call each of your methods | Yes |
+| `backend/app/permissions.json` | Generated method policy | No |
 | `backend/app/main.py` | Runs the App on the runtime's channel | Rarely |
 | `backend/tests/` | unittest tests; `support.call` plays the runtime | Yes |
 | `backend/vendor/synopkgland_app` | The Python SDK for tests, copied by `synopkgland init` from the SDK release; the build ships its own copy of the release `backend.sdk` names | No |
@@ -68,7 +69,8 @@ runtime CGI at `ui/cgi/api.cgi`.
 ## Add a method
 
 Register it in `build`. Every method defaults to DSM administrator membership;
-all access rules live in `backend/app/permissions.json`:
+declare metadata and access rules in `operations.json`; `ctl generate` writes
+`backend/app/permissions.json`:
 
 ```python
 def build(cfg):
@@ -179,3 +181,21 @@ bounded private copy for the worker; no browser session or NAS picker is used.
 Submit with `hash.submit`; use `hash.get` for progress and `hash.cancel` to
 cancel. These handlers call the existing `bg.submit`, `bg.get` and `bg.cancel`
 services; the runtime checks the input path and binds ownership to the caller.
+
+## Operation registry
+
+Declare each App method once in `operations.json`, including its English summary,
+params/result schemas, effect, permission, flow and required `ai` class. The
+SDK contributes its own hidden operation catalog for enabled capability routes.
+Register the handler, then run `synopkgland ctl generate`, `synopkgland ctl
+generate --check` and `synopkgland check`. Build refuses generated drift or a
+route/spec mismatch. Never maintain commands or operation descriptions in the
+manifest or skill by hand. Read the generated `generated/operations.md`.
+
+`examples/operations.json` illustrates read, preview, draft, human-only and hidden.
+It is documentation only: its operations have no handlers and are never shipped
+as commands. Copy a declaration only when implementing a real App capability.
+Draft writes require a non-mutating preview and explicit human confirmation.
+Long operations use the existing job flow; tools own polling and pagination.
+
+Use a matching SDK/CLI/templates release containing the registry support.

package/templates/native-python/backend/app/permissions.json

@@ -1,5 +1,7 @@
 {
   "schema": 1,
   "default": "administrators",
-  "methods": {}
+  "methods": {
+    "app.status": "administrators"
+  }
 }

package/templates/native-python/backend/app/routes.py

@@ -1,13 +1,10 @@
-"""The App's methods. Register a method in build() and give it a rule in
-permissions.json unless only administrators may call it: the runtime has
-checked the DSM session, the entry gate and that rule before a handler runs.
+"""Register real handlers here; operations.json owns metadata and permissions.
+Run ctl generate and ctl generate --check after adding a handler.
 """
 
-import json
 import os
 import platform
 import sys
-import tempfile
 import time
 
 from synopkgland_app import App, Error
@@ -15,7 +12,6 @@ from synopkgland_app import App, Error
 import delegate
 import jobs
 import root_ops
-from params import fields
 
 
 class Config:
@@ -35,8 +31,6 @@ class Config:
 def build(cfg):
     app = App()
     app.method("app.status")(lambda ctx, params: status(cfg, ctx))
-    app.method("greeting.get")(lambda ctx, params: get_greeting(cfg))
-    app.method("greeting.set")(lambda ctx, params: set_greeting(cfg, ctx, params))
     # Each capability module is a stub until `synopkgland init --with` adds its example.
     for capability in (jobs, root_ops, delegate):
         capability.register(app, cfg)
@@ -72,36 +66,3 @@ def installed_version(cfg):
     except OSError:
         pass
     return ""
-
-
-def greeting_path(cfg):
-    return os.path.join(cfg.data_dir, "greeting.json")
-
-
-def get_greeting(cfg):
-    try:
-        with open(greeting_path(cfg), encoding="utf-8") as f:
-            return json.load(f)
-    except FileNotFoundError:
-        return {"text": "Hello"}
-
-
-def set_greeting(cfg, ctx, params):
-    text = fields(params, text=str)["text"]
-    if not 1 <= len(text) <= 200:
-        raise Error.bad_request("text must be 1 to 200 characters")
-    greeting = {"text": text, "updated_by": ctx.user}
-    write_file_atomic(greeting_path(cfg), json.dumps(greeting).encode())
-    return greeting
-
-
-def write_file_atomic(path, data):
-    """Replace path in one rename, so readers never see half a file."""
-    fd, tmp = tempfile.mkstemp(dir=os.path.dirname(path), prefix=".tmp-")
-    try:
-        with os.fdopen(fd, "wb") as f:
-            f.write(data)
-        os.replace(tmp, path)
-    except BaseException:
-        os.unlink(tmp)
-        raise

package/templates/native-python/backend/tests/test_routes.py

@@ -1,4 +1,3 @@
-import json
 import os
 import tempfile
 import unittest
@@ -49,24 +48,9 @@ class RoutesTest(unittest.TestCase):
         self.assertTrue(reply.ok, reply.error)
         self.assertNotIn("portal", reply.data)
 
-    def test_greeting_defaults_to_hello(self):
-        self.assertEqual(call(self.app, "greeting.get").data, {"text": "Hello"})
-
-    def test_greeting_set_stores_the_text_and_who_set_it(self):
-        reply = call(self.app, "greeting.set", {"text": "Hi 👋"}, user="alice")
-        self.assertEqual(reply.data, {"text": "Hi 👋", "updated_by": "alice"})
-        self.assertEqual(call(self.app, "greeting.get").data, {"text": "Hi 👋", "updated_by": "alice"})
-        self.assertEqual(os.listdir(self.data), ["greeting.json"])
-
-    def test_greeting_counts_characters_not_bytes(self):
-        self.assertTrue(call(self.app, "greeting.set", {"text": "é" * 200}).ok)
-
-    def test_greeting_set_refuses_invalid_params_and_keeps_the_old_text(self):
-        for params in [None, [], {}, {"text": ""}, {"text": "x" * 201}, {"text": 5}, {"text": "hi", "extra": 1}]:
-            with self.subTest(params=params):
-                reply = call(self.app, "greeting.set", params)
-                self.assertEqual(reply.error["code"], "bad_request")
-        self.assertEqual(os.listdir(self.data), [])
+    def test_sample_operations_are_absent(self):
+        for method in ("greeting.get", "greeting.set"):
+            self.assertFalse(call(self.app, method).ok)
 
 
 if __name__ == "__main__":

package/templates/native-python/dsm-package.yaml

@@ -47,7 +47,7 @@ backend:
   runtime: python
   dir: backend/app
   entry: main.py
-  sdk: 0.43.0
+  sdk: 0.47.0
 
 ui:
   # Non-UI-SDK frontends open a full page; Portal is a separate opt-in.
@@ -91,33 +91,7 @@ capabilities: {}
 # backup:
 #   hyper_backup: false
 
-# Explicit AI commands. Internal/UI methods are not automatically exposed.
+# Operation metadata has one source. Generate/check before building.
 ctl:
   enabled: true
-  commands:
-    status.show:
-      cli: [status]
-      summary: Show this App's status and verified caller
-      effect: read
-      flow: {type: invoke, method: app.status}
-      paramsSchema: {type: object, additionalProperties: false}
-      examples: [{}]
-    greeting.get:
-      cli: [greeting, get]
-      summary: Read the greeting
-      effect: read
-      flow: {type: invoke, method: greeting.get}
-      paramsSchema: {type: object, additionalProperties: false}
-      examples: [{}]
-    greeting.set:
-      cli: [greeting, set]
-      summary: Set the greeting
-      effect: write
-      flow: {type: invoke, method: greeting.set}
-      paramsSchema:
-        type: object
-        required: [text]
-        additionalProperties: false
-        properties:
-          text: {type: string, minLength: 1, maxLength: 200, description: Greeting text, examples: [Hello]}
-      examples: [{text: Hello}]
+  registry: operations.json

package/templates/native-python/examples/operations.json

@@ -0,0 +1,112 @@
+{
+  "format": "synopkgland.api",
+  "version": 2,
+  "operations": {
+    "example.read": {
+      "summary": "Read a resource",
+      "ai": "read",
+      "cli": [
+        "example",
+        "read"
+      ],
+      "effect": "read",
+      "permission": "administrators",
+      "paramsSchema": {
+        "type": "object",
+        "additionalProperties": false
+      },
+      "resultSchema": {
+        "type": "object"
+      },
+      "flow": {
+        "type": "invoke",
+        "method": "example.read"
+      }
+    },
+    "example.preview": {
+      "summary": "Preview a resource change",
+      "ai": "preview",
+      "cli": [
+        "example",
+        "preview"
+      ],
+      "effect": "read",
+      "permission": "administrators",
+      "paramsSchema": {
+        "type": "object",
+        "additionalProperties": false
+      },
+      "resultSchema": {
+        "type": "object"
+      },
+      "flow": {
+        "type": "invoke",
+        "method": "example.preview"
+      }
+    },
+    "example.draft": {
+      "summary": "Draft a resource change for human confirmation",
+      "ai": "draft",
+      "cli": [
+        "example",
+        "draft"
+      ],
+      "effect": "write",
+      "permission": "administrators",
+      "paramsSchema": {
+        "type": "object",
+        "additionalProperties": false
+      },
+      "resultSchema": {
+        "type": "object"
+      },
+      "flow": {
+        "type": "invoke",
+        "method": "example.draft"
+      },
+      "preview": "example.preview"
+    },
+    "example.human": {
+      "summary": "Delete a resource after human review",
+      "ai": "human-only",
+      "cli": [
+        "example",
+        "human"
+      ],
+      "effect": "destructive",
+      "permission": "administrators",
+      "paramsSchema": {
+        "type": "object",
+        "additionalProperties": false
+      },
+      "resultSchema": {
+        "type": "object"
+      },
+      "flow": {
+        "type": "invoke",
+        "method": "example.human"
+      }
+    },
+    "example.hidden": {
+      "summary": "Read internal state",
+      "ai": "hidden",
+      "cli": [
+        "example",
+        "hidden"
+      ],
+      "effect": "read",
+      "permission": "administrators",
+      "paramsSchema": {
+        "type": "object",
+        "additionalProperties": false
+      },
+      "resultSchema": {
+        "type": "object"
+      },
+      "flow": {
+        "type": "invoke",
+        "method": "example.hidden"
+      }
+    }
+  }
+}

package/templates/native-python/operations.json

@@ -0,0 +1,27 @@
+{
+  "format": "synopkgland.api",
+  "version": 2,
+  "operations": {
+    "app.status": {
+      "summary": "Read App status",
+      "ai": "read",
+      "cli": [
+        "app",
+        "status"
+      ],
+      "effect": "read",
+      "permission": "administrators",
+      "paramsSchema": {
+        "type": "object",
+        "additionalProperties": false
+      },
+      "resultSchema": {
+        "type": "object"
+      },
+      "flow": {
+        "type": "invoke",
+        "method": "app.status"
+      }
+    }
+  }
+}

package/templates/native-python-delegate/operations.patch.json

@@ -0,0 +1,20 @@
+{
+  "operations": {
+    "report.save": {
+      "summary": "Save an example report",
+      "ai": "hidden",
+      "effect": "write",
+      "permission": "authenticated",
+      "cli": [
+        "report",
+        "save"
+      ],
+      "paramsSchema": {},
+      "resultSchema": {},
+      "flow": {
+        "type": "invoke",
+        "method": "report.save"
+      }
+    }
+  }
+}