@synopackageland/cli 0.3.10 → 0.4.0

package/dist/templates/native-go-vue/README.md

@@ -0,0 +1,110 @@
+# __DISPLAY_NAME__ — Vue DSM package
+
+This is the existing native-go template with the shared UI **0.4.0**. It uses
+AppRoot, the DSM embedded theme, Dialog, SettingsSection, Callout and existing
+controls. The generated `dsm-package.yaml` remains the only package manifest.
+
+```sh
+cd frontend
+npm ci --ignore-scripts --no-audit --no-fund
+npm test
+cd ..
+synopkgland validate
+synopkgland build-spk
+synopkgland inspect --spk dist/__PACKAGE__-0.1.0-0001-x86_64.spk
+```
+
+The pinned `@synopackageland/ui@0.4.0` dependency is public on
+`https://registry.npmjs.org`, selected by `frontend/.npmrc`. No registry account
+or credentials are required. Dependencies are installed and UI bundled on the
+build machine; the NAS never downloads npm packages. Commit your lockfiles.
+
+## Optional integration (experimental)
+
+**Experimental integration — DSM 7.4 known limitation:** DSM ignores a
+stop hook refusal. If the helper is ready, Package Stop can mark the package
+stopped while the root helper remains alive. Use administrator **Teardown**
+first, verify the helper is no longer ready, then Stop the package. V1 found
+this on a real NAS; the M1e investigation is ongoing.
+
+Generate with `synopkgland init -t native-go --ui vue --integration go <dir>`.
+This automatically chooses root privilege and adds only the existing M1a
+`integration: {protocol: 1, workers: {}}` contract. The native-go baseline without
+these options remains unchanged. Vue alone keeps the original Go 1.24 module;
+integration uses Go **1.25+** for fd-rooted atomic storage updates.
+
+Open the app as a DSM administrator. **Approve and activate** uses the existing
+DSM PasswordConfirm and exact-task readback, then `helper_enable`. Recover,
+Teardown and Disable call the other fixed public operations. Status always
+comes from `integration.status`; scheduler approval is not helper readiness.
+Package running is `unknown`, scheduler `not-probed`: this backend has no fresh
+Package Center/scheduler probe. Use Package Center separately to read that state.
+The legacy root panel is retained, including its task removal controls.
+
+Normal users see status/error guidance and their own private synthetic note.
+`personal.list/read/write` re-authenticate DSM, require a fresh ready helper,
+resolve the trusted local account and bind the note handle to package/name/UID/GID.
+The backend rejects unknown user/path fields and other users' handles, including
+for administrators. Notes are package-owned data, **not** NAS shared-folder files
+or subtree grants. Directory accounts, account recreation/UID reuse, NAS ACL,
+and M2 grant/revoke/in-flight semantics remain unvalidated. A bounded note write
+that passed readiness may finish while an administrator disables the helper.
+
+The note and lock files are confined with `os.Root`, reject symlink/hardlink and
+unsafe file metadata, serialize CGI readers/writers, and limit UTF-8 input to
+4096 bytes. Failed writes must be inspected/retried; no multi-file transaction,
+version history or general filesystem permission is implied.
+
+## Optional Better Auth
+
+Generate with `--ui vue --integration better-auth`. This is the only option that
+adds `node/`, `identity.*` routes and the `Node.js_v22` DSM dependency. Before
+building, also run `cd node && npm ci --ignore-scripts && npm test && cd ..`.
+The existing SPK builder bundles Better Auth **1.7.7** at build time; it runs as
+the package account, one Node invocation per CGI, without a privileged Node
+listener or shared service. DSM runtime path is
+`/var/packages/Node.js_v22/target/usr/local/bin/node`; actual DSM/CPU support is
+pending acceptance. Go-only does not install or invoke Node/Better Auth.
+
+The CGI verifies native login and local principal again on every identity call,
+mints a fresh random one-use ticket for the private stdin transport, and supplies
+no DSM cookie to Node. A Better Auth session is separately bound to the native
+principal and package. `identity.login/current/logout` consume a ticket. App
+sessions expire in 60 seconds without refresh/cookie cache; placeholder email is
+unverified and is never an identity-linking key. The app-session cookie travels
+as an opaque CGI parameter and stays only in this Vue mount's memory, not a
+browser-wide cookie/localStorage. A serialized package-owned JSON snapshot plus
+secret survives CGI exits under an exclusive lock and atomic rename. This is a
+bounded example adapter; production DB/schema/account lifecycle policy is M2.
+
+## Host lifecycle and local evidence
+
+The existing DSM window loads `app.js/app.css` and registers in
+`window.DsmPackageApps[package]`; each mount creates its own Vue app. Unmount
+clears instance/session state and stale reopen callbacks become no-ops.
+`frontend/test/apps.test.ts` checks states, cancellation, controls, two package
+IDs, overlay roots, reopen/unmount, errors and empty data with jsdom. Real
+unsigned artifact tests additionally cross-compile Go and bundle UI/Node.
+
+UI **0.4.0** enables `<AppRoot modal-scope="app">`. Each mount assigns a
+package-prefixed, instance-unique Vue `idPrefix` before mounting. The sizing
+class on the mount element fills the existing bounded DSM fit-layout body;
+AppRoot fills that element and owns the background scroll container and local
+portal. Other hosts must supply a bounded parent height too. Unmount removes
+only the sizing class added by this mount.
+
+The disable dialog blocks only its own app background. Other package windows
+remain interactive; simultaneous local dialogs have distinct title/description
+IDs. App-local dialogs omit `aria-modal`, and the host must provide a window
+switch mechanism. Do not mix app-local and document overlays in one UI runtime,
+import raw external Reka primitives, or add custom portals outside AppRoot.
+Interoperability with other UI versions/modal libraries and screen-reader or
+Safari/iOS acceptance remains unvalidated. The template has no new NAS proof;
+see the repository's M1b acceptance plan for final-SPK validation.
+
+Every kernel uses the owning supervisor
+with PDEATHSIG; only the parent signals its unreaped child, whose PID cannot be
+reused before reaping. Startup still requires a live handshake within two seconds.
+Lost supervisors preserve failed/cleanup-required; the controller never signals a
+recorded PID. Rebuild after M1d and approve the new payload digest before use.
+Uninstall retains disabled gate/cache/history by policy.

package/dist/templates/native-go-vue/frontend/DESIGN.md

@@ -0,0 +1,78 @@
+---
+name: Native DSM Vue integration template
+description: Existing package settings UI using Syno Package Land UI 0.4.0.
+typography:
+  body:
+    fontFamily: "var(--ui-font-sans)"
+    fontSize: "13px"
+    lineHeight: 1.5
+  title:
+    fontSize: "20px"
+    fontWeight: 600
+  state:
+    fontSize: "15px"
+    fontWeight: 600
+spacing:
+  actions: "8px"
+  heading-gap: "16px"
+  section-gap: "24px"
+---
+
+# Design System: Native DSM Vue integration template
+
+## Overview
+
+This records the built template, not a new visual identity. The settings surface operates inside a DSM package window: users inspect integration health, administrators approve maintenance operations, and each account edits its own synthetic sample note. Its usage mode is **Operate**; preserve the compact, readable hierarchy and existing native component behavior.
+
+Visual authority is `@synopackageland/ui` **0.4.0**, its public exports and `themes/dsm7-embedded.css`, plus the application styles in `src/style.css`. `AppRoot` scopes the component world. Local synthetic browser screenshots (`ui-desktop.png`, `ui-minimum.png`, `ui-user-failed.png`) support this description; they do not establish DSM runtime acceptance.
+
+## Colors
+
+The embedded theme owns the palette. Application text, account/version metadata, status labels, help and completion notices use the existing `--ui-text` token. Do not duplicate sampled screenshot colors as new palette tokens.
+
+Use the existing `primary` Button treatment for activation, note saving and optional app-session creation. Routine refresh, recovery, teardown and opening the disable confirmation use `secondary`; the confirmation itself uses `danger`. Request errors use a danger Callout and explicit recovery copy.
+
+**Pending U2:** inherited Dialog description color and SettingsSection colors/borders require upstream review. Application copy already uses `--ui-text`; this document does not imply that inherited contrast or palette limitations are resolved.
+
+## Typography
+
+Application body copy uses the theme sans family and the body role above. Package title uses the title role; integration state uses the state role. Library components retain their own typography. Keep state descriptions and permissions in plain sentences; do not add display typography to this settings window.
+
+## Layout
+
+A single vertical flow presents package/account metadata and Refresh, followed by non-collapsible integration, sample-data and optional identity sections. Application padding is `var(--ui-space-5, 20px)` and content has a `72ch` maximum width. The heading is a horizontal flex row; action rows wrap. Status metadata uses a two-column definition list with `4px` row and `16px` column gaps. Fields stack labels above controls.
+
+The local fixture covers a **960×640** window and **640×420** minimum window. Preserve vertical scrolling at the smaller height: sections and the note editor continue below the first viewport. Do not compress all content into that viewport or introduce horizontal scrolling.
+
+## Elevation & Depth
+
+The application adds no shadows or elevation system. Surface, overlay and dialog treatments remain owned by the embedded library theme.
+
+## Components
+
+- **AppRoot and lifecycle:** `mount(root, ctx)` creates a fresh Vue instance per DSM window. Reopen refreshes its status. Unmount marks the instance disposed and clears its app cookie, note text and opaque note ID; pending responses must not repopulate a disposed instance. Do not share user/session state between mounts.
+- **SettingsSection and status:** integration is always visible; sample data appears only in `ready`. Keep the six existing labels and descriptions from `context.ts`: `not-enabled` → Not enabled; `ready` → Ready; `needs-approval` → Approval required; `incompatible` → Incompatible; `stopped` → Stopped; `failed` → Failed. Show cleanup-required guidance and the returned package/scheduler values, including `unknown` or `not-probed`.
+- **Permissions and Button:** root controls appear only for an administrator with `ctx.root` and configured integration. Other accounts receive administrator guidance when integration is not ready. Activation/recovery/teardown/disable follow authorization before execution; cancelled approval reports that no operation ran.
+- **Loading, empty and mutation states:** Refresh and mutations disable competing controls; the main region exposes `aria-busy` and textual status. Failed status loading offers Refresh. A ready integration with no note ID shows the “No sample data” Callout. A labeled Textarea and Save button appear when a note exists. Completion notices use `role=status`; error copy uses `role=alert` and identifies a recovery action. Optional app identity appears only when its route reports `better-auth`.
+- **Dialog:** Disable opens the library confirmation dialog, explains refusal of new requests and retention of existing data/output, and presents Cancel plus danger Confirm disable. No application modal replacement is provided.
+
+**App-local modality:** consume UI 0.4.0's `AppRoot modal-scope="app"`.
+Each independent mount sets a package-prefixed, unique Vue `idPrefix` before
+mounting. The mount sizing class and AppRoot use `height: 100%` inside the
+existing bounded DSM fit-layout body. AppRoot owns background scrolling and
+local overlay containment. Other hosts must also supply a bounded parent height.
+The disable dialog makes only its own background inert/aria-hidden and leaves
+other apps and the host interactive. Two local dialogs may remain open; title
+and description references must stay unique even for two mounts of one package.
+The host provides window switching; app-local dialogs omit `aria-modal`.
+Do not mix document/app overlays in one runtime, external Reka primitives or
+custom out-of-root portals. Other UI versions/modal libraries, Safari/iOS and
+manual screen-reader acceptance remain unvalidated. Test the generated final
+SPK on DSM separately from local jsdom/Chromium evidence.
+
+## Do's and Don'ts
+
+- Do use existing public UI components, embedded theme tokens and state/recovery copy.
+- Do retain permission gating, readable loading/empty/error states and per-instance cleanup.
+- Don't claim trusted helper readiness from scheduler values or treat app identity as native session/filesystem authorization.
+- Don't introduce a separate palette, component system or modal workaround around the library contract.