@synopackageland/cli 0.7.3 → 0.9.0

package/CHANGELOG.md

@@ -1,5 +1,254 @@
 # Changelog
 
+## Unreleased (0.9.0)
+
+The CLI, the SDK and the project templates are now three repositories, and
+the CLI only packages, deploys and checks. An App names its SDK version once,
+in `backend/go.mod`. Background saves can create subfolders and choose what
+happens on a name conflict, and time-limited delegate jobs gain read, rename,
+copy, move and delete.
+
+繁中摘要：CLI 移到 github.com/synopackageland/syno-pkg-land-cli，只負責打包、部署與檢查；
+範本改由 `@synopackageland/templates`（精確 pin）提供；SDK 是
+`github.com/synopackageland/syno-pkg-land-sdk`（Go）與 `@synopackageland/sdk`（前端，含
+`./vue`），版本只寫在 `backend/go.mod`。`build` 依該版本 `go mod download`
+executor 並比對 CLI 內建的 sha256 表。`check` 新增 `SDK_REQUIRED`、
+`SDK_VERSION_MISMATCH`、`SDK_UNSUPPORTED`。`files.moveFromStaging` 的 `name`
+可帶子資料夾，新增 `conflict: fail|overwrite|rename`；有時限的 delegate 新增
+`files.read`、`files.rename`、`files.copy`、`files.move`、`files.delete`。
+管理員只在 executor policy 改變時需要重新核准；0.9.0 的 policy 有改變。
+
+### Repositories and the SDK version
+
+- The CLI is github.com/synopackageland/syno-pkg-land-cli, published as
+  `@synopackageland/cli`. The SDK is github.com/synopackageland/syno-pkg-land-sdk: the Go
+  module `github.com/synopackageland/syno-pkg-land-sdk` and the npm package
+  `@synopackageland/sdk`, which includes the Vue components at
+  `@synopackageland/sdk/vue`.
+- The `require github.com/synopackageland/syno-pkg-land-sdk` line in `backend/go.mod` is the
+  only SDK version. `dsm-package.yaml` has no SDK field.
+- `check` and `build` report `SDK_REQUIRED` when `capabilities.delegate` or
+  `rootOps` is declared without that line (an `entry` mode without it fails
+  with `STANDALONE_ENTRY_UNSUPPORTED`), `SDK_UNSUPPORTED` when its minor version is not the CLI's (CLI 0.9.x builds
+  SDK 0.9.x), and `SDK_VERSION_MISMATCH` when the frontend's
+  `@synopackageland/sdk` differs from it. A `file:` frontend dependency is
+  compared through that folder's `package.json` version.
+- `build` reads the SDK version from `backend/go.mod`, runs `go mod download`
+  for the executor of that version, and builds it with go1.26.9. Its sha256
+  must match the table shipped in this CLI, or the build fails with
+  `EXECUTOR_DIGEST_MISMATCH`. A version Go cannot fetch fails with
+  `SDK_DOWNLOAD_FAILED`. While the SDK repositories are private, set
+  `GOPRIVATE=github.com/synopackageland/*` and give git a credential for
+  github.com; the error says which of the two is missing. Root task scripts
+  and `sdk-permissions.json` come from the same SDK version.
+- The CGI binds both policy digests at link time:
+  `<module>/internal/api.expectedPermissionsDigest` for the App and
+  `github.com/synopackageland/syno-pkg-land-sdk/api.expectedSDKPermissionsDigest` for the
+  SDK.
+- `@synopackageland/cli/authorization-sdk` exports `AUTHORIZATION_RUNTIME`
+  and `ROOT_RUNTIME`. `authorizationTemplateDirectory` is removed;
+  `AuthorizationGate` is in `@synopackageland/sdk/vue`.
+
+### Templates
+
+- `init` and `add` read the templates from `@synopackageland/templates`, a
+  dependency pinned to an exact version. `SYNOPKGLAND_TEMPLATES_DIR` points
+  them at a templates checkout; without either, `TEMPLATES_MISSING`.
+- `init` fills the placeholders in every generated file; the Go module path
+  of a new backend is the package id. The next steps say
+  `(cd frontend && npm install)`: the templates ship no lockfile.
+- `init` and `add` share one capability overlay table (`root-ops`, `jobs`,
+  `delegate`).
+
+### Local SDK checkout
+
+- With `SYNOPKGLAND_SDK_DIR`, `init` adds
+  `replace github.com/synopackageland/syno-pkg-land-sdk => $SYNOPKGLAND_SDK_DIR` to
+  `backend/go.mod` and sets the frontend dependency to
+  `file:$SYNOPKGLAND_SDK_DIR/ts`; install it with
+  `(cd frontend && npm install --install-links)`, which packs the SDK like the
+  released package. npm does not build a `file:` package, so a Vue project
+  needs `(cd $SYNOPKGLAND_SDK_DIR/ts && npm ci && npm run build)` first, and
+  again after SDK changes; `init` refuses a checkout without `ts/dist`, or
+  without a root `go.mod`, with `SDK_DIR_NOT_READY`.
+- `build` uses `$SYNOPKGLAND_SDK_DIR/executor`, skips the digest table and
+  warns with `EXECUTOR_DIGEST_UNVERIFIED`. Do not
+  publish such an SPK; the release script refuses to run while
+  `SYNOPKGLAND_SDK_DIR` or `SYNOPKGLAND_TEMPLATES_DIR` is set.
+
+### Delegate: subfolders and conflict policy
+
+- `files.moveFromStaging` (Go: `delegate.MoveParams.Name`) accepts folders
+  below the destination, for example `Album/CD1/01.flac`. The executor's move
+  child creates missing folders as the user, after the final revoke check, so
+  a canceled move leaves none behind. Existing folders are reused. Limits: 16
+  folders, 255 bytes per name, 1024 bytes in total. A name without folders
+  behaves exactly as before.
+- New `conflict` field for `files.moveFromStaging` and the time-limited
+  `files.write`: `fail` (default, unchanged), `overwrite` (atomic replace of a
+  regular file the user can write) or `rename` (`name (1).ext` up to
+  `name (99).ext`; the receipt path reports the name used).
+- New error codes: `invalid-path`, `path-too-deep`,
+  `destination-not-directory`, `name-too-long`.
+
+### Delegate: file operations for time-limited grants
+
+- New operations `files.read`, `files.rename`, `files.copy`, `files.move` and
+  `files.delete`, each declared on its own; a write operation never implies
+  delete. Go: `job.Files()` returns `delegate.JobFiles` with `Read`, `Rename`,
+  `CreateFolderAll`, `Copy`, `Move`, `Delete`, `TaskStatus` and `CancelTask`.
+- `files.createFolder` takes `parents` (`CreateFolderAll`, like `mkdir -p`).
+- Except `files.write` and `files.read`, the executor calls File Station as the
+  user through one root-side allowlist of methods, and re-checks the paths File
+  Station reports against the grant. `files.read` copies the file into staging
+  in a child that drops to the user and never follows symlinks.
+- Copy, move and delete run as File Station background tasks followed with the
+  implied `files.taskStatus` and `files.taskCancel`; revoking the grant stops
+  them. Delete needs `recursive` for folders and goes to the recycle bin; a
+  Shared Folder without one needs `permanent`.
+- File Station refusals now report SDK codes (`PERMISSION_DENIED`,
+  `not-found`, `destination-exists`, `NO_SPACE`, `invalid-path`,
+  `name-too-long`) instead of `DSM_FAILED`. New codes: `not-a-file`,
+  `recursive-required`, `recycle-bin-disabled`, `task-not-found`,
+  `too-many-tasks`, `READ_FAILED`.
+
+### Approval
+
+- An administrator approves the executor policy (operations, scope and root
+  tasks), not the executor binary. When an upgrade keeps the policy and the
+  new executor matches the `INFO` anchor, it installs without a new approval.
+  When the policy changes, the App stays at `needs-admin-approval` until an
+  administrator approves again.
+- The 0.9.0 policy changes (new operations and `conflict`), so a delegate App
+  rebuilt with this CLI needs one new approval after the upgrade.
+  Moving the SDK to its own repository does not add one. Apps not rebuilt are
+  not affected.
+
+## 0.8.0 (2026-10-11)
+
+Faster builds, one SPK checker for any package, and a guide for scripts and
+interpreted languages. `validate` is merged into `inspect`.
+
+繁中摘要：toolkit 改用使用者層級共用快取；新增 `build --jobs` 多架構並行與
+`build --verify-reproducible` 可重現檢查（可用依賴指紋略過）；`inspect` 對任何
+SPK 檢查 DSM 7 格式，synopkgland 建置的 SPK 另查建置合約；native layout 的
+aarch64 INFO arch 改寫機型清單、拒絕無執行權限的 script、toolkit 可用 GNU tar
+或 bsdtar 解開；新增腳本／直譯語言打包指南。無圖示的 native layout SPK 現在會
+因 `SPK_ICON_MISSING` 無法通過 inspect。
+
+### Shared toolkit cache
+
+- Native layout toolkit archives now default to one per-user cache shared by
+  every project and worktree: `$XDG_CACHE_HOME/synopkgland` or
+  `~/.cache/synopkgland` on Linux, `~/Library/Caches/synopkgland` on macOS.
+  `SYNOPKGLAND_CACHE_DIR` still overrides it. The project's
+  `.synopkgland-cache` folder is no longer used by default; delete it or point
+  `SYNOPKGLAND_CACHE_DIR` at it. The private-folder and `sha256` checks are
+  unchanged, and concurrent builds may share the cache.
+
+### Parallel architecture builds
+
+- `synopkgland build --jobs <n>` builds up to `n` architectures at the same
+  time for native-go, binary, native layout and Compose gateway projects. The
+  default stays `1`. Output files and names are byte-identical to a sequential
+  build; with `n` above 1 each output line is prefixed with its architecture.
+- SPK files now reach the output folder only after every architecture
+  succeeds, also with `--jobs 1`. A failed architecture is named in the error,
+  for example `[aarch64]`, and no SPK from that build is written. Before, the
+  architectures built before the failure stayed in `dist/`.
+- Native layout compile hooks get `SYNOPKGLAND_WORK_DIR`, an empty scratch
+  folder per architecture. `--jobs` above 1 requires `layout.payload` to
+  contain `{arch}`. Architectures that pin the same toolkit archive download it
+  once.
+- New error code `CLI_JOBS_INVALID`.
+
+### Reproducible build check
+
+- `synopkgland build --verify-reproducible [changed|always]` keeps this
+  build's SPKs as the first round, builds once more into a temporary folder
+  with an empty `GOCACHE` after removing the manifest's `reproducible.clean`
+  paths, and fails with `BUILD_NOT_REPRODUCIBLE` listing the payload and
+  metadata files that differ. Works for every project type.
+- New optional manifest block `reproducible: {inputs, clean}` in
+  `dsm-package.yaml` (native-go, binary, native layout) and
+  `synology-app.yaml`. The SHA-256 of the `inputs` files, the CLI version and
+  native layout toolkit pins form a dependency fingerprint. A passing check
+  writes it to `reproducible-fingerprint.json`; `changed` (the default) skips
+  the second build while it is unchanged. New error code
+  `REPRODUCIBLE_INVALID`.
+
+### `inspect` checks any SPK
+
+- `synopkgland inspect <spk>` now checks any SPK against the DSM 7 package
+  format, whether `synopkgland` built it or not, without installing it: the
+  outer archive, `INFO` fields, formats and `checksum`, path and link safety in
+  `package.tgz`, `ui/config` JSON and its `"texts"` declaration, ELF files
+  against `arch` (none in `noarch`), lifecycle scripts and their execute bit,
+  `conf/privilege` and `conf/resource`, icons, `LICENSE`, wizards and
+  `syno_signature.asc`. Every finding has a stable `SPK_*` code listed in the
+  errors reference.
+- Only an SPK that `synopkgland` built (top-level `sdk-package.json` or
+  `native-layout.json`, or `synology-app.yaml` in the payload) is also checked
+  against the build contract. Other SPKs are no longer rejected by it.
+- The output has a DSM format section and, for `synopkgland` SPKs, a
+  `synopkgland` contract section. An error in either exits 1 with
+  `SPK_INSPECTION_FAILED`; warnings alone exit 0. `--json` keeps every earlier
+  field and adds `synopkgland` (boolean) and `dsm: {ok, errors, warnings}`.
+- There is no `validate` command; the DSM rules it had during 0.8.0
+  development are part of `inspect`. The project check is `check`.
+
+### Native layout fixes
+
+- `arches: [aarch64]` now writes the same `INFO` `arch` as native-go and
+  binary (`armada37xx rtd1296 rtd1619 rtd1619b`) instead of `aarch64`, which
+  the Developer Guide arch table does not list.
+- `build` refuses a lifecycle or replace script in `layout.metadata` without
+  the execute bit with `NATIVE_LAYOUT_SCRIPT_NOT_EXECUTABLE`; run `chmod +x`.
+  Before, the SPK was built and DSM could not run the script.
+- `native.toolkits` archives extract with GNU tar and with bsdtar (the macOS
+  default). Other tar programs fail with `NATIVE_TOOLKIT_TAR_UNSUPPORTED`.
+  Members with absolute or `..` paths are refused.
+
+### Scripts and interpreted languages guide
+
+- New guide: package a shell, Node.js, Python, Bun or Deno program by
+  compiling it to one executable, bundling the interpreter through
+  `native.toolkits`, or running it in a Compose container, with measured sizes,
+  architectures and glibc needs, and a hand-packed `noarch` shell SPK. The CLI
+  cannot declare `install_dep_packages` for Package Center's Node.js or Python
+  packages; the guide says so.
+
+### 繁體中文摘要
+
+- `synopkgland build --jobs <n>` 可同時建置多個架構（native-go、binary、native layout、
+  Compose gateway），預設仍為 1；產出與依序建置逐位元組相同。所有架構成功後才寫入
+  SPK，失敗時錯誤標明架構且不寫入任何 SPK。native layout hook 新增
+  `SYNOPKGLAND_WORK_DIR`；`--jobs` 大於 1 時 `layout.payload` 必須含 `{arch}`。
+- `synopkgland build --verify-reproducible` 以這次建置為第一輪、從乾淨狀態再建一次比對，
+  不同時列出 payload 檔案並以 `BUILD_NOT_REPRODUCIBLE` 失敗。manifest 新增
+  `reproducible: {inputs, clean}`；依賴指紋未變時略過（記錄在
+  `reproducible-fingerprint.json`）。
+- native layout 的 toolkit 快取預設改為每位使用者一份、所有專案與 worktree 共用
+  （Linux `$XDG_CACHE_HOME/synopkgland` 或 `~/.cache/synopkgland`，macOS
+  `~/Library/Caches/synopkgland`）；`SYNOPKGLAND_CACHE_DIR` 仍可覆寫。專案內的
+  `.synopkgland-cache` 不再預設使用。
+- `synopkgland inspect <spk>` 改為不安裝、依 DSM 7 套件格式檢查任何 SPK（不限本 CLI 建置），
+  涵蓋外層封存、`INFO` 欄位與 `checksum`、`package.tgz` 路徑與連結安全、`ui/config` 的
+  `"texts"`、ELF 與 `arch`（`noarch` 不得有 ELF）、生命週期指令碼與執行權限、`conf/privilege`
+  與 `conf/resource`、圖示、`LICENSE`、精靈與簽章。每個問題有固定 `SPK_*` 代碼，列在錯誤碼參考。
+- 只有 `synopkgland` 建置的 SPK（最上層有 `sdk-package.json` 或 `native-layout.json`，或 payload
+  有 `synology-app.yaml`）另查建置合約；其他 SPK 不再因合約被拒。任一區段有錯誤時以
+  `SPK_INSPECTION_FAILED` 結束碼 1 失敗，只有警告時結束碼 0。`--json` 保留原有欄位，新增
+  `synopkgland` 與 `dsm: {ok, errors, warnings}`。
+- 沒有 `validate` 指令；0.8.0 開發期間的 DSM 規則已併入 `inspect`。專案檢查請用 `check`。
+- native layout 以 `arches: [aarch64]` 建置時，INFO `arch` 改為與 native-go／binary 相同的
+  `armada37xx rtd1296 rtd1619 rtd1619b`。`layout.metadata` 的指令碼沒有執行權限時 `build` 以
+  `NATIVE_LAYOUT_SCRIPT_NOT_EXECUTABLE` 拒絕，請 `chmod +x`。`native.toolkits` 可用 GNU tar 與
+  bsdtar 解壓，其他 tar 以 `NATIVE_TOOLKIT_TAR_UNSUPPORTED` 失敗。
+- 新增「封裝指令碼與直譯式語言」指南：編譯成單一執行檔、經 `native.toolkits` 附帶直譯器、或以
+  Compose 容器執行，附實測大小、架構與 glibc 需求，以及手動打包的 `noarch` shell SPK。CLI 無法宣告
+  `install_dep_packages` 依賴套件中心的 Node.js／Python 套件，指南已明確說明。
+
 ## 0.7.3 (2026-10-11)
 
 Rebuild every package built with 0.7.2 that has `i18n.info` translations. In

package/README.md

@@ -18,7 +18,7 @@ Native Go apps need Go 1.25+ and npm. The CLI is tested on Node.js 22.19.
 ```sh
 synopkgland init -t native-go --with files,jobs,login --package MyApp my-app
 cd my-app
-(cd frontend && npm ci)
+(cd frontend && npm install)
 synopkgland check --json
 synopkgland build --arch x86_64 --json
 synopkgland inspect dist/MyApp-0.1.0-0001-x86_64.spk --json
@@ -40,6 +40,27 @@ the SPK with Package Center's Manual Install.
 Existing native products with their own payload layout use `backend: {kind: native}` in
 `dsm-package.yaml`.
 
+## SDK and templates
+
+The CLI packages, deploys and checks. The app-side code is the SDK
+([synopackageland/syno-pkg-land-sdk](https://github.com/synopackageland/syno-pkg-land-sdk)): the Go module
+`github.com/synopackageland/syno-pkg-land-sdk` and the npm package `@synopackageland/sdk` (Vue components at
+`@synopackageland/sdk/vue`). The `require github.com/synopackageland/syno-pkg-land-sdk` line in
+`backend/go.mod` is the app's only SDK version; `build` compiles the executor of that version
+and checks it against the digests shipped in this CLI. CLI 0.9.x builds SDK 0.9.x.
+
+The SDK repositories are private for now, so Go cannot fetch them from proxy.golang.org. Set
+`go env -w GOPRIVATE=github.com/synopackageland/*` and give git a credential that can read
+`https://github.com/synopackageland/syno-pkg-land-sdk` (check with `git ls-remote`); a failed
+fetch reports `SDK_DOWNLOAD_FAILED` with the step that is missing.
+
+`init` and `add` read their templates from `@synopackageland/templates`, an exact-pinned
+dependency. For development against local checkouts, set `SYNOPKGLAND_TEMPLATES_DIR` to a
+templates checkout and `SYNOPKGLAND_SDK_DIR` to an SDK checkout; SPKs built with
+`SYNOPKGLAND_SDK_DIR` warn `EXECUTOR_DIGEST_UNVERIFIED` and must not be published. A Vue project
+packs the local SDK into its frontend (`npm install --install-links`) without building it: run
+`npm ci && npm run build` in `$SYNOPKGLAND_SDK_DIR/ts` first, and again after SDK changes.
+
 ## Capabilities
 
 Add them with `init --with …` or later with `synopkgland add <capability…>`.
@@ -64,7 +85,7 @@ Device lifecycle acceptance on real hardware is still pending for delegate and r
 | `add` | Add capabilities or `portal` to a project |
 | `check` | Validate the manifest, capability combinations and Compose file |
 | `build` | Build the SPK for one or more architectures |
-| `inspect` | Inspect an SPK without installing it |
+| `inspect` | Check any SPK against the DSM 7 package format without installing it; SPKs built by synopkgland also get the build contract |
 | `deploy` | Build and install on a NAS |
 | `status` | Show package state, Open URL and capability readiness |
 | `logs` | Show package status diagnostics |
@@ -86,14 +107,15 @@ UI components and `npx --no syno-pkg-land-ui describe Button --json` describes o
 
 ## Licensing
 
-The CLI and its original templates are MIT licensed, Copyright (c) 2026 synopkgland.
+The CLI is MIT licensed, Copyright (c) 2026 synopkgland.
 Third-party components keep their own terms.
 
 - Generated projects keep the template terms in `LICENSES/TEMPLATE.txt`. `init` does not choose a
   license for your app: add your own `LICENSE`.
 - An SPK carries its legal notices under `LICENSES/` in the installed payload: `TEMPLATE.txt`,
-  an optional `APP.txt`, Go's license, patents and third-party notices, and the Vue UI notices.
-- Vue builds generate the UI notices from the installed, locked dependencies; run `npm ci` in
+  an optional `APP.txt`, `SDK.txt` (the SDK's MIT license, when `backend/go.mod` requires the SDK),
+  Go's license, patents and third-party notices, and the Vue UI notices.
+- Vue builds generate the UI notices from the installed dependencies; run `npm install` in
   `frontend/` first. A missing notice or version mismatch fails the build.
 - Keep `backend/THIRD_PARTY_NOTICES.txt` current when you change Go modules. Your own binaries,
   added modules, container images and upstream apps need their own notices.

package/dist/add.js

@@ -5,19 +5,9 @@ import { isScalar, parseDocument } from 'yaml';
 import { capabilityNames, capabilitySettings } from './capabilities.js';
 import { initFromTemplate, nativeCapabilitySettings } from './init.js';
 import { templatesRoot } from './template-paths.js';
+import { borrowedTarget, capabilityOverlays } from './capability-overlays.js';
 import { DEFAULT_MIN_DSM, isDsmAtLeast, PORTAL_MIN_DSM } from './build-spk/dsm-version.js';
 import { loadStandaloneManifest } from './standalone/manifest.js';
-const overlays = {
-    jobs: ['native-go-jobs'],
-    'root-ops': ['native-go-root-ops'],
-    delegate: ['native-go-jobs', 'native-go-delegate'],
-    files: ['native-go-files'], login: ['native-go-identity'],
-};
-const removed = {
-    jobs: ['backend/internal/app/background_none.go'],
-    'root-ops': ['backend/internal/app/root_none.go'],
-    delegate: ['backend/internal/app/background_none.go', 'backend/internal/app/root_none.go', 'backend/internal/app/delegate_none.go'],
-};
 function files(root, dir = root) {
     if (!existsSync(dir))
         return [];
@@ -106,12 +96,9 @@ export function addCapabilities(root, requested) {
         const before = join(work, 'before'), generated = join(work, 'generated');
         initFromTemplate('native-go', before, { ui: m.ui.build ? 'vue' : 'plain', with: existingNames, packageId: m.package, displayName: m.displayname });
         initFromTemplate('native-go', generated, { ui: m.ui.build ? 'vue' : 'plain', with: [...existingNames, ...added], packageId: m.package, displayName: m.displayname });
-        const destinations = [...new Set(added.flatMap(name => overlays[name].flatMap(overlay => files(join(templatesRoot(), overlay)))))].filter(file => existsSync(join(generated, file)));
-        if (added.includes('delegate'))
-            destinations.push('backend/internal/background/store.go', 'backend/internal/app/executor.go', 'backend/internal/app/executor_test.go', 'backend/internal/api/sdk-permissions.json');
-        if (added.includes('jobs') || added.includes('delegate') || added.includes('root-ops'))
-            destinations.push('backend/internal/app/routes_test.go');
-        const deletions = added.flatMap(name => removed[name] ?? []);
+        const capability = capabilityOverlays(added);
+        const destinations = [...new Set([...capability.overlays.flatMap(overlay => files(join(templatesRoot(), overlay))), ...capability.borrowed.map(borrowedTarget)])].filter(file => existsSync(join(generated, file)));
+        const deletions = capability.removed;
         const conflicts = [];
         for (const file of destinations) {
             if (existsSync(join(before, file)) && safePath(root, file) && existsSync(join(root, file)) && lstatSync(join(root, file)).isFile() && readFileSync(join(root, file)).equals(readFileSync(join(before, file))))

package/dist/authorization-sdk.d.ts

@@ -4,4 +4,3 @@
  */
 export { ROOT_RUNTIME, type RootTask } from './standalone/native-root-window.js';
 export { AUTHORIZATION_RUNTIME } from './standalone/native-authorization-window.js';
-export declare const authorizationTemplateDirectory: URL;

package/dist/authorization-sdk.js

@@ -4,4 +4,3 @@
  */
 export { ROOT_RUNTIME } from './standalone/native-root-window.js';
 export { AUTHORIZATION_RUNTIME } from './standalone/native-authorization-window.js';
-export const authorizationTemplateDirectory = new URL('../templates/native-authorization/', import.meta.url);

package/dist/build-spk/gateway.d.ts

@@ -21,11 +21,11 @@ export declare function buildGatewayBinary(input: {
     config: GatewayConfig;
     work: string;
     run?: CommandRunner;
-}): {
+}): Promise<{
     binary: string;
 } | {
     error: GatewayErrorCode;
     detail: string;
-};
+}>;
 /** Puts the CGI (mode 0755) and its readable configuration into the package payload. */
 export declare function writeGatewayPayload(packageDir: string, binary: string, config: GatewayConfig): void;

package/dist/build-spk/gateway.js

@@ -3,7 +3,7 @@ import { join } from "node:path";
 import { checkCgiBinary } from "../standalone/binary.js";
 import { runCommand } from "../standalone/build.js";
 import { resolvedWebAccess } from "../contract/web-launch.js";
-import { templatesRoot } from "../template-paths.js";
+import { goAssetDir } from "../template-paths.js";
 import { PINNED_GO_HINT, pinnedGoBuildEnv, pinnedGoProblem } from "./go-toolchain.js";
 export { gatewayEntryPath } from "../contract/web-launch.js";
 /** Where the gateway CGI sits in the package payload; DSM serves `ui/` under /webman/3rdparty/<package>/. */
@@ -24,11 +24,11 @@ export function gatewayConfig(contract, adminport) {
     };
 }
 /** Compiles the fixed gateway module for `arch`; the result is a static ELF or a coded failure. */
-export function buildGatewayBinary(input) {
+export async function buildGatewayBinary(input) {
     const out = join(input.work, `gateway-${input.arch}.cgi`);
     const ldflags = ["-s", "-w", "-buildid=", `-X main.packageID=${input.packageId}`, `-X 'main.configJSON=${JSON.stringify(input.config)}'`].join(" ");
-    const result = (input.run ?? runCommand)("go", ["build", "-trimpath", "-buildvcs=false", "-ldflags", ldflags, "-o", out, "."], {
-        cwd: join(templatesRoot(), "_gateway"),
+    const result = await (input.run ?? runCommand)("go", ["build", "-trimpath", "-buildvcs=false", "-ldflags", ldflags, "-o", out, "."], {
+        cwd: goAssetDir("gateway"),
         env: { ...process.env, ...pinnedGoBuildEnv(input.arch) },
     });
     if (result.missing) {

package/dist/build-spk/generator.d.ts

@@ -20,6 +20,7 @@ export interface BuildSpkResult {
     errors: string[];
 }
 export declare function buildSpk(options: BuildSpkOptions): Promise<BuildSpkResult>;
+export declare function walkFiles(root: string, prefix?: string): string[];
 export declare function digestSpkPayload(spkPath: string): Promise<string>;
 export declare function extractSpk(spkPath: string, targetDir: string): Promise<void>;
 export declare function readInfoPackage(spkDir: string): string | null;

package/dist/build-spk/generator.js

@@ -99,7 +99,7 @@ export async function buildSpk(options) {
     try {
         let gatewayBinary;
         if (gateway) {
-            const built = buildGatewayBinary({
+            const built = await buildGatewayBinary({
                 packageId: String(contract.package),
                 arch: options.archFamily,
                 config: gateway,
@@ -862,7 +862,7 @@ async function createDeterministicSpk(stagingDir, outputPath) {
     }
     await createReproducibleTar(stagingDir, outputPath);
 }
-function walkFiles(root, prefix = "") {
+export function walkFiles(root, prefix = "") {
     const files = [];
     for (const entry of readdirSync(root).sort()) {
         const relative = prefix ? `${prefix}/${entry}` : entry;

package/dist/build-spk/notices.js

@@ -1,5 +1,6 @@
 import { copyFileSync, existsSync, lstatSync, mkdirSync, readFileSync, readdirSync } from 'node:fs';
 import { dirname, join } from 'node:path';
+import { sdkRequirement, sdkSource } from '../runtime/sdk-source.js';
 /** Copy legal text only; never follow a project-supplied symlink. */
 export function copyNoticeTree(source, target) {
     const stat = lstatSync(source);
@@ -28,7 +29,7 @@ export function copyProjectNotices(root, payload) {
 export function copyStandaloneNotices(root, uiDir, payload, go, goDir = join(root, 'backend')) {
     copyProjectNotices(root, payload);
     const dest = join(payload, 'LICENSES');
-    const shared = new URL('../../templates/_shared/', import.meta.url);
+    const shared = new URL('../../assets/licenses/', import.meta.url);
     if (go) {
         mkdirSync(dest, { recursive: true });
         for (const name of ['GO-LICENSE', 'GO-PATENTS'])
@@ -36,14 +37,17 @@ export function copyStandaloneNotices(root, uiDir, payload, go, goDir = join(roo
         if (existsSync(join(goDir, 'THIRD_PARTY_NOTICES.txt')))
             copyNoticeTree(join(goDir, 'THIRD_PARTY_NOTICES.txt'), join(dest, 'GO-THIRD_PARTY_NOTICES.txt'));
     }
-    const nativeAdmin = join(goDir, 'internal/dsm/native');
-    if (go && existsSync(join(nativeAdmin, 'admin_check.c'))) {
-        for (const name of ['admin_check.c', 'apppriv_check.c', 'build.sh', 'provenance.json', 'licenses']) {
-            // Projects scaffolded before the AppPriv bridge carry only the administrator bridge.
-            if (name === 'apppriv_check.c' && !existsSync(join(nativeAdmin, name)))
-                continue;
+    // The SDK's dsm package embeds the native administrator and AppPriv bridges; their sources and terms ship with them.
+    const sdk = go ? sdkRequirement(goDir) : undefined;
+    if (sdk) {
+        const source = sdkSource(sdk);
+        const license = join(source.goDir, 'LICENSE');
+        if (!existsSync(license))
+            throw new Error(`[NOTICE_MISSING] SDK license missing: ${license}`);
+        copyNoticeTree(license, join(dest, 'SDK.txt'));
+        const nativeAdmin = join(source.goDir, 'dsm/native');
+        for (const name of ['admin_check.c', 'apppriv_check.c', 'build.sh', 'provenance.json', 'licenses'])
             copyNoticeTree(join(nativeAdmin, name), join(dest, 'native-admin', name));
-        }
     }
     const frontend = join(root, 'frontend/package.json');
     const usesUi = existsSync(frontend) && Boolean(JSON.parse(readFileSync(frontend, 'utf8')).dependencies?.['@synopackageland/ui']);

package/dist/capability-overlays.d.ts

@@ -0,0 +1,15 @@
+/**
+ * How each native-go capability is laid over the base template: the template
+ * directories copied on top, files borrowed from another overlay, and the
+ * base files the overlay replaces. init and add both read this table.
+ */
+export interface CapabilityOverlay {
+    overlays: string[];
+    borrowed: string[];
+    removed: string[];
+}
+export declare const CAPABILITY_OVERLAYS: Record<string, CapabilityOverlay>;
+/** The overlays of these capabilities, in table order, each once; a capability without one adds nothing. */
+export declare function capabilityOverlays(names: readonly string[]): CapabilityOverlay;
+/** A borrowed path names its overlay first; this is where it lands in a project. */
+export declare const borrowedTarget: (path: string) => string;

package/dist/capability-overlays.js

@@ -0,0 +1,18 @@
+const EXECUTOR_SHELL = ['backend/internal/app/executor.go', 'backend/internal/app/executor_test.go'];
+export const CAPABILITY_OVERLAYS = {
+    'root-ops': { overlays: ['native-go-root-ops'], borrowed: [], removed: ['backend/internal/app/root_none.go'] },
+    jobs: { overlays: ['native-go-jobs'], borrowed: [], removed: ['backend/internal/app/background_none.go'] },
+    delegate: {
+        overlays: ['native-go-jobs', 'native-go-delegate'],
+        borrowed: EXECUTOR_SHELL.map(file => `native-go-root-ops/${file}`),
+        removed: ['backend/internal/app/background_none.go', 'backend/internal/app/root_none.go', 'backend/internal/app/delegate_none.go'],
+    },
+};
+/** The overlays of these capabilities, in table order, each once; a capability without one adds nothing. */
+export function capabilityOverlays(names) {
+    const chosen = Object.entries(CAPABILITY_OVERLAYS).filter(([name]) => names.includes(name)).map(([, overlay]) => overlay);
+    const unique = (pick) => [...new Set(chosen.flatMap(pick))];
+    return { overlays: unique(o => o.overlays), borrowed: unique(o => o.borrowed), removed: unique(o => o.removed) };
+}
+/** A borrowed path names its overlay first; this is where it lands in a project. */
+export const borrowedTarget = (path) => path.split('/').slice(1).join('/');

package/dist/cli-version.d.ts

@@ -0,0 +1,2 @@
+/** This CLI's own release, read from its package.json. */
+export declare const CLI_VERSION: string;

package/dist/cli-version.js

@@ -0,0 +1,3 @@
+import { readFileSync } from "node:fs";
+/** This CLI's own release, read from its package.json. */
+export const CLI_VERSION = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version;