@synopackageland/templates 0.40.1 → 0.40.3

package/templates/_shared/AGENTS.md

@@ -22,9 +22,52 @@ sections at the end name each language's files, types and test commands.
 
 From the project root, run `synopkgland check --json`,
 `synopkgland build --json`, then `synopkgland inspect <spk> --json` on the emitted SPK.
-For Vue, first run `npm ci`, `npm test` and `npm run build` in frontend.
+For Vue, first run `npm ci --include=dev` and `npm run build` in frontend. Run its tests only if the user chose tests.
 Do not connect to or change a NAS without explicit task authorization.
 
+## Optional testing
+
+Ask once whether the user wants tests: none, local/non-AI, or optional AI too.
+Accept no tests, remember the choice, do not nag and never block a build or release
+on tests. Scaffolding is included by default; writing and running tests are optional.
+Read `synopkgland skill show testing` when setting up or extending tests.
+
+The default `npm test` runs only fast local unit/ctl registry contracts.
+At the project root, run `npm install --include=dev` first; after committing its
+lockfile, use `npm ci --include=dev`.
+`NODE_ENV=production` skips devDependencies; `test:local` needs the CLI and frontend builds need dev tools.
+Before `test:local`, prepare the backend/frontend as described below and run
+`synopkgland ctl generate` for a native App.
+`npm run test:local` opts into check/build/inspect. Only on explicit user request,
+run `npm run test:nas:ctl`, `npm run e2e:smoke`, `npm run e2e:ui` or `npm run e2e:ai`.
+The full suite is slow. Never call these from build, install, DSM hooks or release.
+For non-AI use, no model/key is required; AI dependencies are optional installs.
+
+Assert meaningful ctl values and the UI primary action's real result, not only
+schemas or page rendering. Adapt the generated examples to actual App operations.
+Long jobs use start -> progress -> pause -> resume without reset -> cancel with
+bounded polling and fixture cleanup; never wait for full completion.
+
+AI steps require a user-selected endpoint, key location and model. If no profile
+is configured and setup is unknown, ask the user for those three values. Choose
+the cheapest adequate model and low effort; never default to an expensive model.
+Use E2E_LLM_BASE_URL, E2E_LLM_MODEL, E2E_LLM_API_KEY_FILE (mode 600) or
+E2E_LLM_API_KEY, and optional E2E_LLM_REASONING_EFFORT (default low).
+
+## Upstream web UI only
+
+For an `--upstream-fork` wrapper whose only UI is the upstream web panel, set
+`ui: false` in `synology/dsm-package.yaml` and configure `identity_gateway`
+for that panel. `--ui plain` selects `ui/app.js`; it does not mean `ui: false`.
+The current scaffold still creates UI and browser-test examples: remove
+`synology/ui/` (or `synology/frontend/` for Vue), `synology/tests/e2e/`,
+`synology/e2e.config.ts` and `synology/e2e.ai.config.ts`, and remove the
+`e2e:*` scripts from `synology/package.json`.
+Keep `synology/backend/`, `synology/i18n/messages/`, `synology/operations.json` and
+the local/ctl tests: the entry gate still needs the backend and message catalogs.
+Read `synopkgland skill show upstream-fork` and
+`synopkgland skill show orchestrator` for the wrapper workflow.
+
 ## Lifecycle scripts (`dsm-scripts/`)
 
 `dsm-scripts/` holds DSM's own lifecycle scripts (preinst, postinst, preupgrade,
@@ -274,8 +317,8 @@ Do not force HTTPS for ordinary CRUD/settings/file Apps. Only secure context
 features, pairing or a strict secure Origin policy justify it. Return
 `https_required`, not a generic authentication error, and render the SDK's
 `identityCopy(locale).httpsTitle` / `errors.https_required` with reopening
-instructions. Go `api.RequireSecureOrigin(request)` is opt-in and does not
-replace authentication, origin or permission checks.
+instructions. Secure-origin enforcement is opt-in and does not replace
+authentication, origin or permission checks.
 
 Call `readDsmPorts` for `dms_https` only when `ctx.user?.isAdmin === true`;
 `readDsmHttpsURL(ctx, location.href)` applies this guard. Ordinary users see
@@ -287,12 +330,14 @@ For an old tab's stale `X-SYNO-TOKEN`, SDK `createClient` can opt in through
 `effect: read`, `kind: rpc` calls retry once on `session_required`. Writes, AI,
 streams, batches and unknown methods never retry. Existing `ctx.call` is not
 automatically wrapped. Verify the installed SDK exports these APIs before
-using them. Follow the [CLI skill](https://github.com/synopackageland/syno-pkg-land-cli/blob/main/skills/SKILL.md#https-與舊-dsm-token)
+using them. Follow the [CLI skill](https://github.com/synopackageland/syno-pkg-land-cli/blob/main/skills/SKILL.md)
 and [SDK guide](https://github.com/synopackageland/syno-pkg-land-sdk/blob/main/docs/https-and-session-recovery.md).
-Test both HTTP/HTTPS entries, both user roles and cross-tab session recovery.
+When the user requests NAS acceptance, test both HTTP/HTTPS entries, both user roles and cross-tab session recovery.
 
 ## Go backend
 
+- `api.RequireSecureOrigin(request)` opts into secure-origin enforcement; it does
+  not replace authentication, origin or permission checks.
 - Routes: `backend/internal/app` (`routes.go` registers them); App
   permissions: `backend/internal/api/permissions.json`. Test with
   `(cd backend && go test ./...)`, then `go vet ./...` and `gofmt -l .`.
@@ -345,7 +390,7 @@ their capabilities with `synopkgland init --with`.
   `new AppError(code, message)`, `AppError.badRequest(message)`. Call services
   through `service(ctx, op, params)` (`service.ts`), which passes the runtime's
   refusals on; a bare `ctx.runtime` refusal would reach the browser as `internal`.
-- Test with `(cd backend && npm ci && npm test && npm run typecheck)`; `test/support.ts`'s
+- Test with `(cd backend && npm ci --include=dev && npm test && npm run typecheck)`; `test/support.ts`'s
   `call` plays the runtime.
 
 ## Rust backend

package/templates/_shared/e2e.ai.config.ts

@@ -0,0 +1,5 @@
+import base from './e2e.config.ts';
+import { e2eAgent } from '@synopackageland/cli/e2e';
+
+// Loaded only by e2e:ai; the default config needs no AI dependencies or key.
+export default { ...base, agents: { default: e2eAgent() } };

package/templates/_shared/package.json

@@ -2,13 +2,17 @@
   "private": true,
   "type": "module",
   "scripts": {
-    "e2e:smoke": "node --env-file-if-exists=.env node_modules/@synopackageland/cli/dist/e2e/dsm.js tunnel -- e2e run tests/e2e/smoke.e2e.ts"
+    "test": "npm run test:unit",
+    "test:unit": "node --test tests/unit/*.test.mjs",
+    "test:local": "node --test tests/local/*.test.mjs",
+    "test:nas:ctl": "node --env-file-if-exists=.env --test tests/ctl/*.test.mjs",
+    "e2e:smoke": "node --env-file-if-exists=.env node_modules/@synopackageland/cli/dist/e2e/dsm.js tunnel -- e2e run tests/e2e/smoke.e2e.ts",
+    "e2e:ui": "node --env-file-if-exists=.env node_modules/@synopackageland/cli/dist/e2e/dsm.js tunnel -- e2e run tests/e2e/action.e2e.ts",
+    "e2e:ai": "node --env-file-if-exists=.env node_modules/@synopackageland/cli/dist/e2e/dsm.js tunnel -- e2e run --config e2e.ai.config.ts tests/e2e/action.ai.e2e.ts"
   },
   "devDependencies": {
-    "@synopackageland/cli": "^0.41.6",
+    "@synopackageland/cli": "~0.48.20",
     "@e2e-dev/web": "^0.14.0",
-    "e2e": "^0.19.0",
-    "@ai-sdk/openai": "^4.0.91",
-    "ai": "^7.0.137"
+    "e2e": "^0.19.0"
   }
 }

package/templates/_shared/tests/ctl/status.test.mjs

@@ -0,0 +1,17 @@
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+import { cli } from '../support/cli.mjs';
+
+// Invoke only on user request, after ctl discovery/approval for this installed App.
+// Replace this starter command and assertions when the App's contract changes.
+test('installed status reports the expected package and administrator', {
+  skip: !process.env.APP_TEST_HOST && 'Set APP_TEST_HOST to an authorized registered host',
+}, () => {
+  const command = JSON.parse(process.env.APP_TEST_CTL_COMMAND || '["app","status"]');
+  assert.ok(Array.isArray(command) && command.length && command.every(x => typeof x === 'string'));
+  const data = cli('ctl', process.env.APP_TEST_APP || '__PACKAGE__', ...command,
+    '--host', process.env.APP_TEST_HOST);
+  assert.equal(data.package, '__PACKAGE__');
+  assert.equal(data.admin, true);
+  assert.ok(data.process.uid > 0, 'the App runs as a nonroot package account');
+});

package/templates/_shared/tests/e2e/action.ai.e2e.ts

@@ -0,0 +1,14 @@
+import assert from 'node:assert/strict';
+import { test } from '@e2e-dev/web';
+import { actionFixture, assertOutcome, openFixture } from './support/action.ts';
+
+// Opt-in semantic step; keep the final result assertion deterministic.
+test('an AI step performs the authorized fixture action', async ({app, browser, agent}) => {
+  const {result, expected} = actionFixture();
+  const instruction = process.env.APP_TEST_AI_ACTION;
+  assert.ok(instruction, 'Set APP_TEST_AI_ACTION to one bounded authorized fixture action');
+  const root = await openFixture(app, browser);
+  assert.notEqual((await root.locator(result).textContent())?.trim(), expected);
+  await agent.act(instruction);
+  await assertOutcome(root, result, expected);
+});

package/templates/_shared/tests/e2e/action.e2e.ts

@@ -0,0 +1,14 @@
+import assert from 'node:assert/strict';
+import { test } from '@e2e-dev/web';
+import { actionFixture, assertOutcome, openFixture } from './support/action.ts';
+
+// An action and its observable result, without a model or AI key.
+// For CRUD, prepare a private fixture first and assert saved/read-back data.
+// For long jobs, replace this with the bounded lifecycle in the testing guide.
+test('the primary action changes the fixture outcome', async ({app, browser}) => {
+  const {action, result, expected} = actionFixture();
+  const root = await openFixture(app, browser);
+  assert.notEqual((await root.locator(result).textContent())?.trim(), expected);
+  await root.locator(action).click();
+  await assertOutcome(root, result, expected);
+});

package/templates/_shared/tests/e2e/support/action.ts

@@ -0,0 +1,30 @@
+import assert from 'node:assert/strict';
+import { setTimeout } from 'node:timers/promises';
+import { openApp, openPortal, readSmokeEntry, signIn } from '@synopackageland/cli/e2e';
+
+// Configure an authorized fixture action with a known, initially different result.
+export function actionFixture() {
+  const action = process.env.APP_TEST_ACTION;
+  const result = process.env.APP_TEST_RESULT;
+  const expected = process.env.APP_TEST_EXPECTED;
+  assert.ok(action && result && expected, 'Set APP_TEST_ACTION, APP_TEST_RESULT and APP_TEST_EXPECTED');
+  return {action, result, expected};
+}
+
+export async function openFixture(app: Parameters<typeof signIn>[0], browser: NonNullable<Parameters<typeof openApp>[3]>) {
+  const entry = readSmokeEntry({entry: process.env.APP_TEST_ENTRY});
+  await signIn(app);
+  return entry.window ? openApp(app, entry.appId, 30_000, browser) : openPortal(app, entry.entry, browser);
+}
+
+type Root = Awaited<ReturnType<typeof openFixture>>;
+export async function assertOutcome(root: Root, result: string, expected: string) {
+  const deadline = Date.now() + 10_000;
+  let actual;
+  do {
+    actual = (await root.locator(result).textContent({timeout: 1000}))?.trim();
+    if (actual === expected) break;
+    await setTimeout(100);
+  } while (Date.now() < deadline);
+  assert.equal(actual, expected, 'the primary action changed its real outcome');
+}

package/templates/_shared/tests/local/package.test.mjs

@@ -0,0 +1,16 @@
+import assert from 'node:assert/strict';
+import { existsSync } from 'node:fs';
+import { test } from 'node:test';
+import { cli } from '../support/cli.mjs';
+
+// Explicit local build tier; no deployment or NAS connection.
+test('the App checks, builds and passes package inspection', {timeout: 300_000}, () => {
+  cli('check');
+  const built = cli('build', '--arch', process.env.APP_TEST_ARCH || 'x86_64');
+  assert.ok(built.outputs.length > 0);
+  for (const spk of built.outputs) {
+    assert.equal(existsSync(spk), true);
+    const inspected = cli('inspect', spk);
+    assert.equal(inspected.spk, spk);
+  }
+});

package/templates/_shared/tests/support/cli.mjs

@@ -0,0 +1,11 @@
+import assert from 'node:assert/strict';
+import { execFileSync } from 'node:child_process';
+
+// Use the actual CLI and its registered host/session, never a direct HTTP shortcut.
+export function cli(...args) {
+  const result = JSON.parse(execFileSync('synopkgland', [...args, '--json'], {
+    encoding: 'utf8', timeout: 120_000, stdio: ['ignore', 'pipe', 'pipe'],
+  }));
+  assert.equal(result.ok, true);
+  return result.data;
+}

package/templates/_shared/tests/unit/registry.test.mjs

@@ -0,0 +1,16 @@
+import assert from 'node:assert/strict';
+import { existsSync, readFileSync } from 'node:fs';
+import { test } from 'node:test';
+
+// Pin meaningful command behavior, not just JSON schema validity.
+const registry = existsSync('operations.json')
+  ? JSON.parse(readFileSync('operations.json', 'utf8')) : undefined;
+test('the starter status command remains a read of app.status', {
+  skip: !registry?.operations?.['app.status'] && 'No starter status operation; add your own unit contract',
+}, () => {
+  const status = registry.operations['app.status'];
+  assert.equal(status.effect, 'read');
+  assert.deepEqual(status.cli, ['app', 'status']);
+  assert.equal(status.flow.type, 'invoke');
+  assert.equal(status.flow.method, 'app.status');
+});

package/templates/binary/README.md

@@ -0,0 +1,16 @@
+# __DISPLAY_NAME__
+
+## Local tests
+
+From the project root, install the test tools before running the optional tests:
+
+```sh
+npm install --include=dev
+npm test
+```
+
+`NODE_ENV=production` skips devDependencies; `test:local` needs the CLI.
+After committing the generated root lockfile, use `npm ci --include=dev`.
+The scaffold provides example prebuilt binaries; replace them with your own
+Linux binaries before packaging. See `AGENTS.md` for the package workflow.
+

package/templates/compose/README.md

@@ -0,0 +1,16 @@
+# __DISPLAY_NAME__
+
+## Local tests
+
+From the project root, install the test tools before running the optional tests:
+
+```sh
+npm install --include=dev
+npm test
+```
+
+`NODE_ENV=production` skips devDependencies; `test:local` needs the CLI.
+After committing the generated root lockfile, use `npm ci --include=dev`.
+Configure the upstream image and its real readiness endpoint before
+`test:local`; see `AGENTS.md` for the Compose packaging workflow.
+

package/templates/native-go/README.md

@@ -25,10 +25,25 @@ independent package-account worker and report phase/progress. Authenticate
 status/result polling by that ID; a slow NAS or failed status read leaves the
 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
+Jobs use the SDK's default operation allowance; 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/main/docs/request-deadlines.md).
 
+## Local tests
+
+From the project root, install the test tools before running the optional tests:
+
+```sh
+npm install --include=dev
+npm test
+```
+
+`NODE_ENV=production` skips devDependencies; `test:local` needs the CLI.
+After committing the generated root lockfile, use `npm ci --include=dev`.
+Before `npm run test:local`, prepare the backend and, for Vue, build the
+frontend using the steps below and the backend section in `AGENTS.md`, then
+run `synopkgland ctl generate`.
+
 ## Quick start
 
 Needs Node.js with `synopkgland` installed, and Go 1.26.10.
@@ -443,3 +458,16 @@ 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.
+
+## Upstream web UI only
+
+`init --upstream-fork --ui plain` still creates a plain SDK UI; it does not
+select `ui: false`. For an upstream web panel with no SDK UI, set `ui: false`
+in `synology/dsm-package.yaml` and configure `identity_gateway` for the panel.
+Remove `synology/ui/` (or `synology/frontend/` for Vue),
+`synology/tests/e2e/`, `synology/e2e.config.ts` and
+`synology/e2e.ai.config.ts`, and remove the `e2e:*` npm scripts.
+Keep `synology/backend/`, `synology/i18n/messages/`, `synology/operations.json` and
+the local/ctl tests: the entry gate still needs the backend and message catalogs.
+Read `synopkgland skill show upstream-fork` and
+`synopkgland skill show orchestrator` for the wrapper workflow.

package/templates/native-go/backend/internal/app/background_test.go

@@ -34,6 +34,10 @@ func newBgEnv(t *testing.T) *bgEnv {
 }
 
 func (e *bgEnv) call(auth api.Authenticator, method, params string) (string, map[string]any) {
+	return e.callContext(context.Background(), auth, method, params)
+}
+
+func (e *bgEnv) callContext(ctx context.Context, auth api.Authenticator, method, params string) (string, map[string]any) {
 	e.t.Helper()
 	// SDK policy provides owner routes immediately.
 	routes := newBackgroundRoutes(e.store, e.dataDir)
@@ -42,6 +46,7 @@ func (e *bgEnv) call(auth api.Authenticator, method, params string) (string, map
 		e.t.Fatal(err)
 	}
 	req := httptest.NewRequest(http.MethodPost, "/api.cgi", strings.NewReader(`{"method":"`+method+`","params":`+params+`}`))
+	req = req.WithContext(ctx)
 	req.Header.Set("Content-Type", "application/json")
 	req.Header.Set("Sec-Fetch-Site", "same-origin")
 	rec := httptest.NewRecorder()
@@ -112,8 +117,18 @@ func TestBackgroundStatusReportsLimitsAndWorker(t *testing.T) {
 		t.Fatalf("%s %v", code, out)
 	}
 	limits := d["limits"].(map[string]any)
-	if limits["maxInputBytes"].(float64) != 512*1024 || limits["maxQueued"].(float64) != 16 || limits["maxTotalBytes"].(float64) != 16<<20 || limits["jobTimeoutSeconds"].(float64) != 30*60 {
-		t.Fatalf("limits: %v", limits)
+	for name, want := range map[string]float64{
+		"maxInputBytes":     background.MaxInputBytes,
+		"maxQueued":         background.MaxQueued,
+		"maxSchedules":      background.MaxSchedules,
+		"maxTotalBytes":     background.MaxTotalBytes,
+		"maxOwnerPending":   background.MaxOwnerPending,
+		"maxOwnerBytes":     background.MaxOwnerBytes,
+		"jobTimeoutSeconds": background.JobTimeout.Seconds(),
+	} {
+		if got := limits[name]; got != want {
+			t.Errorf("limits[%q] = %v, want %v", name, got, want)
+		}
 	}
 	info := background.WorkerInfo{PID: os.Getpid(), UID: os.Getuid(), Username: "pkg"}
 	if err := e.store.Heartbeat(context.Background(), info); err != nil {

package/templates/native-go-jobs/backend/internal/app/background_routes_test.go

@@ -52,7 +52,7 @@ func TestBackgroundBusyErrorCode(t *testing.T) {
 	}
 }
 
-func TestBackgroundRequestSubmitBusyAndProductionConstruction(t *testing.T) {
+func TestBackgroundRequestSubmitDeadlineAndProductionConstruction(t *testing.T) {
 	e := newBgEnv(t)
 	dir := filepath.Join(t.TempDir(), "background")
 	e.store = background.NewRequestStore(dir)
@@ -68,12 +68,17 @@ func TestBackgroundRequestSubmitBusyAndProductionConstruction(t *testing.T) {
 		t.Fatal(err)
 	}
 	defer syscall.Flock(int(f.Fd()), syscall.LOCK_UN)
+	// Use an earlier caller deadline instead of waiting for the SDK's full
+	// operation allowance. The API reports that deadline, not jobs_busy.
+	budget := min(50*time.Millisecond, background.RequestLockTimeout/2)
+	ctx, cancel := context.WithTimeout(context.Background(), budget)
+	defer cancel()
 	start := time.Now()
-	code, out := e.call(alice, "bg.jobs.submit", e.submitParams("k1"))
-	if code != "jobs_busy" || time.Since(start) > background.RequestLockTimeout+time.Second {
-		t.Fatalf("busy submit: %s %+v", code, out)
+	code, out := e.callContext(ctx, alice, "bg.jobs.submit", e.submitParams("k1"))
+	if code != "request_timeout" || time.Since(start) > budget+time.Second {
+		t.Fatalf("submit deadline: %s %+v", code, out)
 	}
-	// The actual production assembly must use the same bounded wait policy.
+	// The production route assembly must also honor an earlier request deadline.
 	srv, err := api.NewServerWithPermissions(alice, []byte(`{"schema":1,"default":"administrators","methods":{}}`), BackgroundRoutes(filepath.Dir(dir))...)
 	if err != nil {
 		t.Fatal(err)
@@ -82,8 +87,8 @@ func TestBackgroundRequestSubmitBusyAndProductionConstruction(t *testing.T) {
 	r.Header.Set("Content-Type", "application/json")
 	r.Header.Set("Sec-Fetch-Site", "same-origin")
 	w := httptest.NewRecorder()
-	srv.ServeHTTP(w, r)
-	if !strings.Contains(w.Body.String(), `"jobs_busy"`) {
+	api.WithRequestDeadline(srv, api.Timeout(budget)).ServeHTTP(w, r)
+	if !strings.Contains(w.Body.String(), `"request_timeout"`) {
 		t.Fatal(w.Body.String())
 	}
 }

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

@@ -7,9 +7,24 @@ files, portal, jobs and delegate components come from `@synopackageland/sdk/vue`
 `github.com/synopackageland/syno-pkg-land-sdk` version in `backend/go.mod`. See
 <https://github.com/synopackageland/syno-pkg-land-sdk> for the components and their props.
 
+## Local tests
+
+From the project root, install the test tools before running the optional tests:
+
+```sh
+npm install --include=dev
+npm test
+```
+
+`NODE_ENV=production` skips devDependencies; `test:local` needs the CLI.
+After committing the generated root lockfile, use `npm ci --include=dev`.
+Before `npm run test:local`, prepare the backend and, for Vue, build the
+frontend using the steps below and the backend section in `AGENTS.md`, then
+run `synopkgland ctl generate`.
+
 ```sh
 cd frontend
-npm ci
+npm ci --include=dev
 npm test
 npm run build
 ```

package/templates/native-node/README.md

@@ -25,16 +25,31 @@ independent package-account worker and report phase/progress. Authenticate
 status/result polling by that ID; a slow NAS or failed status read leaves the
 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
+Jobs use the SDK's default operation allowance; 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/main/docs/request-deadlines.md).
 
+## Local tests
+
+From the project root, install the test tools before running the optional tests:
+
+```sh
+npm install --include=dev
+npm test
+```
+
+`NODE_ENV=production` skips devDependencies; `test:local` needs the CLI.
+After committing the generated root lockfile, use `npm ci --include=dev`.
+Before `npm run test:local`, prepare the backend and, for Vue, build the
+frontend using the steps below and the backend section in `AGENTS.md`, then
+run `synopkgland ctl generate`.
+
 ## Quick start
 
 Needs Node.js 20 or later with `synopkgland` installed. The SPK depends on DSM's **Node.js v20** package (INFO `install_dep_packages`).
 
 ```bash
-(cd backend && npm ci && npm test && npm run build)   # method tests, then app/*.js
+(cd backend && npm ci --include=dev && npm test && npm run build)   # method tests, then app/*.js
 synopkgland ctl generate
 synopkgland check
 synopkgland build           # → dist/__PACKAGE__-0.1.0-0001-{x86_64,aarch64}.spk

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

@@ -42,7 +42,7 @@ arches: [x86_64, aarch64]
 # and app/permissions.json, then runs `node main.js` in backend/app as the
 # package account, once per call, with Package Center's Node.js (node.package
 # becomes an install dependency). backend/src compiles to backend/app: run
-# `npm ci` and `npm run build` in backend before check and build. sdk is the
+# `npm ci --include=dev` and `npm run build` in backend before check and build. sdk is the
 # SDK release whose runtime and Node SDK (node_modules/@synopackageland/app)
 # the build ships; the build reads the methods from `main.js --describe`.
 backend:

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

@@ -7,9 +7,24 @@ delegate components come from `@synopackageland/sdk/vue` (types from
 `@synopackageland/sdk`); its version must equal the `backend.sdk` in dsm-package.yaml. See
 <https://github.com/synopackageland/syno-pkg-land-sdk> for the components and their props.
 
+## Local tests
+
+From the project root, install the test tools before running the optional tests:
+
+```sh
+npm install --include=dev
+npm test
+```
+
+`NODE_ENV=production` skips devDependencies; `test:local` needs the CLI.
+After committing the generated root lockfile, use `npm ci --include=dev`.
+Before `npm run test:local`, prepare the backend and, for Vue, build the
+frontend using the steps below and the backend section in `AGENTS.md`, then
+run `synopkgland ctl generate`.
+
 ```sh
 cd frontend
-npm ci
+npm ci --include=dev
 npm test
 npm run build
 ```

package/templates/native-python/README.md

@@ -25,10 +25,25 @@ independent package-account worker and report phase/progress. Authenticate
 status/result polling by that ID; a slow NAS or failed status read leaves the
 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
+Jobs use the SDK's default operation allowance; 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/main/docs/request-deadlines.md).
 
+## Local tests
+
+From the project root, install the test tools before running the optional tests:
+
+```sh
+npm install --include=dev
+npm test
+```
+
+`NODE_ENV=production` skips devDependencies; `test:local` needs the CLI.
+After committing the generated root lockfile, use `npm ci --include=dev`.
+Before `npm run test:local`, prepare the backend and, for Vue, build the
+frontend using the steps below and the backend section in `AGENTS.md`, then
+run `synopkgland ctl generate`.
+
 ## Quick start
 
 Needs Node.js with `synopkgland` installed, and Python 3.8 or later.

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

@@ -7,9 +7,24 @@ delegate components come from `@synopackageland/sdk/vue` (types from
 `@synopackageland/sdk`); its version must equal the `backend.sdk` in dsm-package.yaml. See
 <https://github.com/synopackageland/syno-pkg-land-sdk> for the components and their props.
 
+## Local tests
+
+From the project root, install the test tools before running the optional tests:
+
+```sh
+npm install --include=dev
+npm test
+```
+
+`NODE_ENV=production` skips devDependencies; `test:local` needs the CLI.
+After committing the generated root lockfile, use `npm ci --include=dev`.
+Before `npm run test:local`, prepare the backend and, for Vue, build the
+frontend using the steps below and the backend section in `AGENTS.md`, then
+run `synopkgland ctl generate`.
+
 ```sh
 cd frontend
-npm ci
+npm ci --include=dev
 npm test
 npm run build
 ```

package/templates/native-rust/README.md

@@ -25,10 +25,25 @@ independent package-account worker and report phase/progress. Authenticate
 status/result polling by that ID; a slow NAS or failed status read leaves the
 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
+Jobs use the SDK's default operation allowance; 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/main/docs/request-deadlines.md).
 
+## Local tests
+
+From the project root, install the test tools before running the optional tests:
+
+```sh
+npm install --include=dev
+npm test
+```
+
+`NODE_ENV=production` skips devDependencies; `test:local` needs the CLI.
+After committing the generated root lockfile, use `npm ci --include=dev`.
+Before `npm run test:local`, prepare the backend and, for Vue, build the
+frontend using the steps below and the backend section in `AGENTS.md`, then
+run `synopkgland ctl generate`.
+
 ## Quick start
 
 Needs Node.js with `synopkgland` installed, Rust through rustup, Zig and `cargo-zigbuild`: `backend/rust-toolchain.toml` pins 1.97.1 with the three DSM targets, so the first `cargo` run installs them.

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

@@ -7,9 +7,24 @@ delegate components come from `@synopackageland/sdk/vue` (types from
 `@synopackageland/sdk`); its version must equal the `syno-pkg-land-app` tag in backend/Cargo.toml. See
 <https://github.com/synopackageland/syno-pkg-land-sdk> for the components and their props.
 
+## Local tests
+
+From the project root, install the test tools before running the optional tests:
+
+```sh
+npm install --include=dev
+npm test
+```
+
+`NODE_ENV=production` skips devDependencies; `test:local` needs the CLI.
+After committing the generated root lockfile, use `npm ci --include=dev`.
+Before `npm run test:local`, prepare the backend and, for Vue, build the
+frontend using the steps below and the backend section in `AGENTS.md`, then
+run `synopkgland ctl generate`.
+
 ```sh
 cd frontend
-npm ci
+npm ci --include=dev
 npm test
 npm run build
 ```