@synopackageland/cli 0.3.10 → 0.4.1

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

@@ -0,0 +1,224 @@
+# __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.
+
+Vitest is pinned to **4.1.11** to fix CVE-2026-47429 and CVE-2026-84373.
+It and `@vitest/mocker` are development-only tools, excluded from the shipped
+browser bundle and SPK. Run `npm audit` separately to check the full lockfile;
+`npm audit --omit=dev` checks only production dependencies. These checks are
+snapshots of the advisory database, not a guarantee against future advisories.
+Keep the `--ignore-scripts` install above: npm install-script policy warnings
+are separate from vulnerability findings and do not require approving scripts
+for this template's test/build workflow.
+
+## 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, Disable and Repair cleanup 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.
+
+## NAS picker and grants (S4 mock preview)
+
+The Vue template includes `NasPathPicker` and `NasGrantSettings`, built from UI
+0.4.0's Dialog, TreeView, DataGrid, Button and SettingsSection. The existing
+browser `FilePicker` still represents local `File[]`; NAS selections return
+opaque directory grant handles. The new UI has catalogs for en, zh-TW, zh-CN,
+ja, ko, de, fr, es and it, selected from `ctx.locale` with English fallback.
+
+There is **no default NAS provider** and no new CGI/helper route. The existing
+DSM loader's two-argument mount remains unchanged and hides the NAS section.
+A development host can explicitly inject an in-memory fixture:
+
+```ts
+import {mount} from './src/main'
+import {createMockNasService} from './src/nas/mock-provider'
+
+const fixtures = createMockNasService({appName: 'My package', drained: false})
+const app = mount(root, ctx, {nasProvider: fixtures.connect('normal1')})
+// Another window can use fixtures.connect('normal2'); private grants stay separate.
+// Call app.unmount() when its window closes or its native subject changes.
+```
+
+Only `normal1`, `normal2` and `admin` are synthetic fixture subjects. The service
+uses S0 protocol-2 display projections and S1 discovery-anchor shape, not native
+identity proofs or filesystem authority. Candidate contexts expire in 60 seconds;
+one-use review intents expire in 30 seconds. Picker cancellation invalidates that
+context and creates no grant. Read-only actions are fixed; shared consent and
+shared revoke require the fixture's current administrator role. Fixture references
+and digest-shaped summary tokens are random; these are **not** S3 authenticated
+digests, durable storage, DSM ACL validation, or transferable grants.
+
+Grant state is separate from helper readiness. Revocation shows R (new access
+refused) separately from Q (transfers drained), including pending cleanup from a
+provider snapshot. It does not undo sent/written data. All fixture state disappears
+when this service instance is discarded. Neither mock success nor abort/timeout
+proves a NAS operation stopped. Each UI request is bounded to five seconds;
+close/unmount aborts pending work and ignores late results. A package/account
+change reported by app status discards the injected UI until the host remounts
+with a new per-session provider. Real adapters must validate the current session, local UID/username, enabled
+account, complete groups and App privilege on every call. Session switches
+require a new provider; relaxed mode accepts same-UID/same-name recreation.
+
+The mock is imported only by tests/development hosts and is not activated or
+bundled by the default entry point. Later S3/S5/S8 work must supply production
+adapters, durable/fence/ACL proofs and capability integration before connecting
+NAS data. Go-only and the existing protocol-1 manifest remain unchanged.
+
+## 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.
+
+
+## Repair after supervisor loss (R2)
+
+An administrator can choose **Repair cleanup** through the existing DSM
+PasswordConfirm and exact `helper_repair` task. Every Repair run asks for fresh
+password confirmation and rechecks the task afterward; cancellation runs nothing. A protected epoch lifetime lock,
+held by both the supervisor and its child until kernel exit, must be obtainable
+before cleanup. Repair clears only verified helper runtime residue, commits a
+private completion proof and preserves the approval/disabled gate. It never
+signals a recorded PID or restarts integration; use Recover or Approve and
+activate separately afterward. Missing, replaced or busy witnesses and foreign
+or live runtime paths refuse cleanup. Repeating Repair safely retries an
+interrupted cleanup transaction.
+
+Pre-R2 builds, including M1d/0001 Alpha and pre-R2 M1g, did not create this
+witness. Upgrading cannot supply historical proof: retain their residue and use
+the separately authorized reboot/Disable flow before upgrading. See
+`docs/m1a-helper-lifecycle-contract.md` in the SDK repository. R2 has local and
+isolated Linux systemd VM evidence; DSM 4.4 acceptance is still unknown.
+
+
+## M2 S1R build policy and unavailable delivery
+
+The S8 source candidate also accepts `--integration-protocol 2` with
+`--integration go` or `better-auth`. The default stays protocol 1. The manifest,
+compiled helper/CGI inventory, payload/worker digests, inspector and lifecycle
+approval pin the same protocol. A change requires exact new approval, never
+protocol 1 data fallback.
+
+Use `--data-access relaxed` with explicit protocol 2 to emit
+`integration.dataAccess: relaxed`. Omission keeps unavailable behavior; explicit
+`unavailable` is also accepted for protocol 2. The setting is bound into helper/CGI
+inventory, digests and root approval. Rebuild and obtain new approval to change it.
+It does not install missing adapters, enable write gates or certify NAS access.
+
+Relaxed identity records UID and username. Recreated accounts with the same pair
+may retain grants; changing either invalidates all grants for that identity and
+requires new authorization. Disabled accounts and revoked App access are denied.
+File operations use permanent dropped credentials and remain limited by NAS
+permissions and grant scope. See `docs/m2-s1r-relaxed-identity.md` in the SDK repo.
+
+NAS folder grants and file operations are not available for ordinary users or
+administrators. Production DSM identity, permission and scope adapters are not yet certified.
+Managed account pilot B is superseded by the relaxed UID/username contract. Enabling or
+recovering integration, or signing in again, does not unlock NAS access.
+Production shows this state in nine languages and supplies no picker/consent/
+file CTA. Only dev/test builds accept an injected mock provider with a preview
+banner; production ignores provider injection. No public data adapter is installed. Caller/admin/path fields never supply
+trusted session, UID, groups or App permission.
+
+Unknown NAS methods return `unknown_method`; the valid nil binary read route
+returns `unsupported`. Missing native proof is `unavailable`, wrong peer is
+`denied`, and unknown/stale/replay controls retain their own safe codes.
+Anonymous/expired DSM sessions return `session_required`; authentication failure
+returns `auth_unavailable`. Relogin restores only the ordinary app session.
+Positive NAS functionality, ACL and final DSM SPK acceptance remain blocked /
+unknown; local refusal and QEMU fixtures do not certify them.

package/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 existing labels and descriptions from `context.ts`: `not-enabled` → Not enabled; `ready` → Ready; `needs-approval` → Approval required; `incompatible` → Incompatible; `stopped` → Stopped; `failed` → Failed; `pending` → Temporarily revalidating (localized safe copy). Pending hides sample authority and does not request administrator recovery. 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.