@synopackageland/templates 0.38.0 → 0.39.0

package/templates/native-python-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-python-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-rust/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, Rust through rustup, Zig and `cargo-
 
 ```bash
 (cd backend && cargo test --locked)   # 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/src/routes.rs` | Your methods: `build` registers them | Yes — your backend |
 | `backend/src/jobs.rs`, `root_ops.rs`, `delegate.rs` | Capability examples (stubs unless `init --with` added them) | Yes |
-| `backend/permissions.json` | Who may call each of your methods | Yes |
+| `backend/permissions.json` | Generated method policy | No |
 | `backend/src/main.rs` | Runs the App on the runtime's channel | Rarely |
 | `backend/src/test_support.rs` | `call` plays the runtime in `cargo test` | Rarely |
 | `backend/Cargo.toml`, `backend/Cargo.lock` | Your crate; the `syno-pkg-land-app` dependency's `tag` pins the SDK, and the committed lock file pins everything else | SDK upgrades |
@@ -69,7 +70,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/permissions.json`:
+declare metadata and access rules in `operations.json`; `ctl generate` writes
+`backend/permissions.json`:
 
 ```rust
 pub fn build(cfg: Config) -> App {
@@ -94,7 +96,7 @@ fn list_notes(_cfg: &Config, ctx: &Context, params: &Params) -> Result<Value, Er
 
 List the method in `backend.methods` in dsm-package.yaml, then add a test next to it with `call(build(cfg), "notes.list", json!({"folder": "work"}), "admin", &services)`. Call it from the UI with `ctx.call("notes.list", { folder: "work" })`.
 
-Return `Error::new(code, message)` (or `Error::bad_request(message)`) for an error the browser may see; use `routes::internal(e)` for anything unexpected, which logs it and answers `internal`. `ctx.runtime` returns the runtime's refusal as an `Error`, so `?` passes its code on to the browser.
+Return `Error::new(code, message)` (or `Error::bad_request(message)`) for an error the browser may see; log unexpected failures server-side and return a generic internal error. `ctx.runtime` returns the runtime's refusal as an `Error`, so `?` passes its code on to the browser.
 
 The runtime refuses before your App runs: `session_required`, `admin_required`,
 `unknown_method`, `request_timeout` and the transport guards' codes. The UI
@@ -188,3 +190,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-rust/backend/Cargo.lock

@@ -104,8 +104,8 @@ dependencies = [
 
 [[package]]
 name = "syno-pkg-land-app"
-version = "0.43.0"
-source = "git+https://github.com/synopackageland/syno-pkg-land-sdk?tag=v0.43.0#263d2a4fbab040756d406b76dd8272bca9db9707"
+version = "0.47.0"
+source = "git+https://github.com/synopackageland/syno-pkg-land-sdk?tag=v0.47.0#c486d2ce888248e9e68a67908810c62f968d601e"
 dependencies = [
  "libc",
  "serde",

package/templates/native-rust/backend/Cargo.toml

@@ -9,7 +9,7 @@ libc = "0.2"
 serde = { version = "1", features = ["derive"] }
 serde_json = "1"
 # The SDK version is the tag; `synopkgland check` reads it from Cargo.lock.
-syno-pkg-land-app = { git = "https://github.com/synopackageland/syno-pkg-land-sdk", tag = "v0.43.0" }
+syno-pkg-land-app = { git = "https://github.com/synopackageland/syno-pkg-land-sdk", tag = "v0.47.0" }
 
 [profile.release]
 # A handler panic becomes an "internal" reply; abort would end the App without one.

package/templates/native-rust/backend/permissions.json

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

package/templates/native-rust/backend/src/routes.rs

@@ -1,21 +1,19 @@
-//! The App's methods. Register a method in `build` and list it in
-//! dsm-package.yaml's `backend.methods`; 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.
 
-use serde::{Deserialize, Serialize};
 use serde_json::{Value, json};
 use std::fs;
-use std::io::{ErrorKind, Write};
-use std::path::{Path, PathBuf};
+use std::path::PathBuf;
 use std::time::{SystemTime, UNIX_EPOCH};
-use syno_pkg_land_app::{App, Context, Error, Params};
+use syno_pkg_land_app::{App, Context};
 
 /// Where the App's state lives; the runtime sets the environment.
 #[derive(Clone)]
 pub struct Config {
     pub package: String,
     /// The package's own data directory (/var/packages/<package>/var), kept across upgrades.
+    // Capability overlays use this persistent state directory.
+    #[allow(dead_code)]
     pub data_dir: PathBuf,
     pub packages_root: PathBuf,
 }
@@ -35,12 +33,6 @@ pub fn build(cfg: Config) -> App {
     let mut app = App::new();
     let c = cfg.clone();
     app.method("app.status", move |ctx, _| Ok(status(&c, ctx)));
-    let c = cfg.clone();
-    app.method("greeting.get", move |_, _| get_greeting(&c));
-    let c = cfg.clone();
-    app.method("greeting.set", move |ctx, params| {
-        set_greeting(&c, ctx, params)
-    });
     // Each capability module is a stub until `synopkgland init --with` adds its example.
     crate::jobs::register(&mut app, &cfg);
     crate::root_ops::register(&mut app, &cfg);
@@ -77,72 +69,6 @@ fn installed_version(cfg: &Config) -> String {
         .unwrap_or_default()
 }
 
-#[derive(Serialize, Deserialize)]
-struct Greeting {
-    text: String,
-    #[serde(skip_serializing_if = "Option::is_none")]
-    updated_by: Option<String>,
-}
-
-#[derive(Deserialize)]
-#[serde(deny_unknown_fields)]
-struct SetGreeting {
-    text: String,
-}
-
-fn greeting_path(cfg: &Config) -> PathBuf {
-    cfg.data_dir.join("greeting.json")
-}
-
-fn get_greeting(cfg: &Config) -> Result<Greeting, Error> {
-    match fs::read(greeting_path(cfg)) {
-        Err(e) if e.kind() == ErrorKind::NotFound => Ok(Greeting {
-            text: "Hello".into(),
-            updated_by: None,
-        }),
-        Err(e) => Err(internal(e)),
-        Ok(data) => serde_json::from_slice(&data).map_err(internal),
-    }
-}
-
-fn set_greeting(cfg: &Config, ctx: &Context, params: &Params) -> Result<Greeting, Error> {
-    let SetGreeting { text } = params.decode()?;
-    if !(1..=200).contains(&text.chars().count()) {
-        return Err(Error::bad_request("text must be 1 to 200 characters"));
-    }
-    let greeting = Greeting {
-        text,
-        updated_by: Some(ctx.user.clone()),
-    };
-    write_file_atomic(
-        &greeting_path(cfg),
-        &serde_json::to_vec(&greeting).map_err(internal)?,
-    )
-    .map_err(internal)?;
-    Ok(greeting)
-}
-
-/// An unexpected failure: logged to stderr (the package's log), `internal` for the browser.
-pub fn internal(e: impl std::fmt::Display) -> Error {
-    eprintln!("{e}");
-    Error::new("internal", "internal error")
-}
-
-/// Replaces path in one rename, so readers never see half a file.
-pub fn write_file_atomic(path: &Path, data: &[u8]) -> std::io::Result<()> {
-    let nanos = SystemTime::now()
-        .duration_since(UNIX_EPOCH)
-        .map_or(0, |d| d.subsec_nanos());
-    let tmp = path.with_file_name(format!(".tmp-{}-{nanos}", std::process::id()));
-    let written = fs::File::create_new(&tmp)
-        .and_then(|mut f| f.write_all(data))
-        .and_then(|_| fs::rename(&tmp, path));
-    if written.is_err() {
-        let _ = fs::remove_file(&tmp);
-    }
-    written
-}
-
 /// Now as 2006-01-02T15:04:05Z.
 pub fn utc_now() -> String {
     let secs = SystemTime::now()
@@ -185,13 +111,6 @@ mod tests {
         (dir, cfg)
     }
 
-    fn files(cfg: &Config) -> Vec<String> {
-        fs::read_dir(&cfg.data_dir)
-            .unwrap()
-            .map(|e| e.unwrap().file_name().into_string().unwrap())
-            .collect()
-    }
-
     #[test]
     fn status_reports_the_caller_and_the_installed_version() {
         let (_dir, cfg) = setup();
@@ -279,74 +198,17 @@ mod tests {
     }
 
     #[test]
-    fn greeting_defaults_to_hello() {
-        let (_dir, cfg) = setup();
-        let reply = call(
-            build(cfg),
-            "greeting.get",
-            Value::Null,
-            "admin",
-            &Services::new(),
-        );
-        assert_eq!(reply.data, json!({"text": "Hello"}));
-    }
-
-    #[test]
-    fn greeting_set_stores_the_text_and_who_set_it() {
+    fn sample_operations_are_absent() {
         let (_dir, cfg) = setup();
-        let reply = call(
-            build(cfg.clone()),
-            "greeting.set",
-            json!({"text": "Hi 👋"}),
-            "alice",
-            &Services::new(),
-        );
-        assert_eq!(reply.data, json!({"text": "Hi 👋", "updated_by": "alice"}));
-        let reply = call(
-            build(cfg.clone()),
-            "greeting.get",
-            Value::Null,
-            "admin",
-            &Services::new(),
-        );
-        assert_eq!(reply.data, json!({"text": "Hi 👋", "updated_by": "alice"}));
-        assert_eq!(files(&cfg), ["greeting.json"]);
-    }
-
-    #[test]
-    fn greeting_counts_characters_not_bytes() {
-        let (_dir, cfg) = setup();
-        let reply = call(
-            build(cfg),
-            "greeting.set",
-            json!({"text": "é".repeat(200)}),
-            "admin",
-            &Services::new(),
-        );
-        assert_eq!(reply.code(), "");
-    }
-
-    #[test]
-    fn greeting_set_refuses_invalid_params_and_keeps_the_old_text() {
-        let (_dir, cfg) = setup();
-        for params in [
-            Value::Null,
-            json!([]),
-            json!({}),
-            json!({"text": ""}),
-            json!({"text": "x".repeat(201)}),
-            json!({"text": 5}),
-            json!({"text": "hi", "extra": 1}),
-        ] {
+        for method in ["greeting.get", "greeting.set"] {
             let reply = call(
                 build(cfg.clone()),
-                "greeting.set",
-                params.clone(),
+                method,
+                Value::Null,
                 "admin",
                 &Services::new(),
             );
-            assert_eq!(reply.code(), "bad_request", "{params}");
+            assert_ne!(reply.code(), "");
         }
-        assert!(files(&cfg).is_empty());
     }
 }

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

@@ -48,7 +48,7 @@ backend:
   runtime: rust
   dir: backend
   entry: app
-  methods: [app.status, greeting.get, greeting.set]
+  methods: [app.status]
 
 ui:
   # Non-UI-SDK frontends open a full page; Portal is a separate opt-in.
@@ -92,33 +92,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-rust/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-rust/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-rust-delegate/backend/Cargo.lock

@@ -170,8 +170,8 @@ dependencies = [
 
 [[package]]
 name = "syno-pkg-land-app"
-version = "0.43.0"
-source = "git+https://github.com/synopackageland/syno-pkg-land-sdk?tag=v0.43.0#263d2a4fbab040756d406b76dd8272bca9db9707"
+version = "0.47.0"
+source = "git+https://github.com/synopackageland/syno-pkg-land-sdk?tag=v0.47.0#c486d2ce888248e9e68a67908810c62f968d601e"
 dependencies = [
  "libc",
  "serde",

package/templates/native-rust-delegate/backend/Cargo.toml

@@ -10,7 +10,7 @@ libc = "0.2"
 serde = { version = "1", features = ["derive"] }
 serde_json = "1"
 # The SDK version is the tag; `synopkgland check` reads it from Cargo.lock.
-syno-pkg-land-app = { git = "https://github.com/synopackageland/syno-pkg-land-sdk", tag = "v0.43.0" }
+syno-pkg-land-app = { git = "https://github.com/synopackageland/syno-pkg-land-sdk", tag = "v0.47.0" }
 
 [profile.release]
 # A handler panic becomes an "internal" reply; abort would end the App without one.

package/templates/native-rust-delegate/backend/src/delegate.rs

@@ -3,7 +3,7 @@
 //! executor moves it to the caller's destination with the caller's own
 //! permission, so the package never needs write access to that folder.
 
-use crate::routes::{Config, internal, utc_now};
+use crate::routes::{Config, utc_now};
 use serde::Deserialize;
 use serde_json::{Value, json};
 use sha2::{Digest, Sha256};
@@ -12,6 +12,12 @@ use std::io::{ErrorKind, Write};
 use std::os::unix::fs::{DirBuilderExt, OpenOptionsExt};
 use syno_pkg_land_app::{App, Context, Error, Params};
 
+// Log unexpected failures privately; return a stable code to the caller.
+fn internal(e: impl std::fmt::Display) -> Error {
+    eprintln!("{e}");
+    Error::new("internal", "internal error")
+}
+
 #[derive(Deserialize)]
 #[serde(deny_unknown_fields)]
 struct SaveReport {

package/templates/native-rust-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"
+      }
+    }
+  }
+}