@synopackageland/cli 0.7.0 → 0.7.2

package/CHANGELOG.md

@@ -1,6 +1,306 @@
 # Changelog
 
-## Unreleased
+## 0.7.2 (2026-10-11)
+
+Rebuild packages to pick up the new default icon. Packages without `icon` now
+show the SDK default icon instead of a solid blue square.
+
+### Package icon
+
+- `dsm-package.yaml` and `synology-app.yaml` accept `icon`: a square PNG of at
+  least 256×256 inside the project, or a folder of `icon_<size>.png` (16, 24,
+  32, 48, 64, 72, 256; `icon_256.png` required, missing sizes scaled from it).
+  `build` writes `PACKAGE_ICON.PNG` (64×64), `PACKAGE_ICON_256.PNG` and every
+  DSM window size `ui/images/app_<size>.png` from it. SVG is not accepted, so
+  the CLI gains no image dependency. `check` refuses an icon outside the
+  project, a non-PNG, a non-square or smaller image, and one whose Package
+  Center icons exceed the package source's 256 KiB limit
+  (`STANDALONE_ICON_INVALID`, `CONTRACT_ICON_INVALID`).
+
+- A native layout may set `icon` too; `build` then writes both Package Center
+  icons and refuses a metadata folder that also ships them. Without `icon` the
+  layout keeps owning its icons.
+
+- `check` reports which icon a build uses: `圖示：自訂 <path>`, or `圖示：SDK
+  預設圖示` with an info hint about `icon:` (not an error). It warns when an
+  icon is a single colour. `check --json` reports it in `data.icon`.
+
+- `inspect` reports `icon` as `default`, `custom` (with the SHA-256 of
+  `PACKAGE_ICON_256.PNG`) or `none`, and lists a Package Center icon over
+  256 KiB, of the wrong size or not a PNG as a finding.
+
+- The SDK default icon replaces the solid blue square in Package Center, the
+  DSM main menu and the window. Sources are in `assets/default-icon/`.
+
+### Translated DSM title
+
+- With `i18n.info` translations, the DSM main-menu entry and window title
+  follow the DSM language. `ui/config` refers to `synopkgland:app_title` and
+  `app_desc` in `ui/texts/<DSM language>/strings`, written for English and each
+  translated language; a language without its own text shows the English one.
+  Without translations `ui/config` keeps the literal English title.
+
+- `synology-app.yaml` accepts the same `i18n.info` block. It writes INFO
+  `displayname_<lang>` / `description_<lang>` and, with `launch: dsm-window`,
+  localizes the DSM window entry. Once a translation exists, the English
+  `displayname` and `description` must also be one line without `"` or `\`
+  (`CONTRACT_I18N_INVALID`).
+
+### Delegate window
+
+- A DSM window built for a `scope: install-selected` delegate no longer
+  contains the dead `if (panels && false)` check. The window leaves out the
+  approval panel code instead, and other scopes generate `if (panels)`. The
+  behavior is unchanged: this scope is approved only in the app's
+  **Administrator setup** panel, because that approval carries the scope the
+  administrator picks and the window panel has no scope picker. The delegate
+  guide now says so.
+
+### 繁體中文摘要
+
+- 升級後重新建置套件即可換上新的 SDK 預設圖示（不再是純藍方塊）。executor digest 不變，不需重新核准。
+- `dsm-package.yaml`、`synology-app.yaml` 與 native layout 新增 `icon`：專案內至少 256×256 的正方形
+  PNG，或含 `icon_256.png` 的 `icon_<size>.png` 目錄；不接受 SVG。`check` 顯示使用的圖示並檢查格式與
+  256 KiB 上限，`inspect` 回報 `default`／`custom`／`none`。
+- 有 `i18n.info` 翻譯時，DSM 主選單與視窗標題會跟著 DSM 語言切換；缺翻譯的語言顯示英文。
+  `synology-app.yaml` 也支援 `i18n.info`。
+- `scope: install-selected` 的 DSM 視窗不再產生 `if (panels && false)` 死碼；此 scope 仍只在 App 的
+  「管理員設定」核准。
+
+## 0.7.1 (2026-10-10)
+
+Rebuild packages to pick up template, hook and executor changes. The executor
+digest changed. A package built with CLI 0.7.0 needs one administrator approval
+after upgrading to a 0.7.1 build: the 0.7.0 executor opened the package
+`target` link without following it, so it cannot install the anchored executor
+itself. Executor-only upgrades between 0.7.1 or later builds need no approval.
+
+### Executor upgrade and daemon timeouts
+
+- During an INFO-anchored executor-only upgrade the executor log said
+  `executor paused: package pins require administrator approval` about two
+  seconds before the new executor was ready. That line now appears only when
+  the pins differ; an anchored handover logs only `executor upgrade:
+  INFO-anchored executor installed under the approved policy`. The executor
+  digest changes.
+
+- `executor_status_mismatch` in the app window and the app's settings names
+  its cause: `the approved executor is not answering (<reason>)`, `the running
+  executor reports other digests than this package pins`, or `the executor
+  status request failed` with the request's own code, instead of `scheduler
+  readback or operation failed` for all three. The Data and removal
+  troubleshooting table explains each.
+
+- After approval or control start the window asked `executor.status` every
+  500 ms for up to 10 s. The wait now doubles from 500 ms to 2 s within the
+  same 10 s budget: at most 7 requests instead of 20.
+
+- For live upgrade tests, the repository's `scripts/test/executor-bump.py`
+  makes an executor-only build+1 SPK and now rewrites the window script's
+  embedded pins with the INFO anchor and `executor/setup.json`. The earlier
+  out-of-tree copy left the window pins behind, so the panel reported
+  `executor_status_mismatch` after every such upgrade while CGI and CLI
+  status were ready.
+
+- On kernel 3.10 (DSM 7.1, for example DS416 armv7) an executor-only
+  upgrade, and approving again while the executor runs, no longer fail
+  with "pid executable mismatch". That kernel names a running executor
+  replaced by a rename after the rename source (`runtime/.executor
+  (deleted)`), and root control accepted only `runtime/executor`. Root
+  control now identifies the monitor by inode: the current
+  `runtime/executor`, or an unlinked root-owned inode on the runtime's
+  device whose last name was `executor` or `.executor*` in the runtime.
+  The fix runs in the new executor, which the installed one starts: an
+  upgrade from a package built with the target-link fix below needs no
+  approval; from 0.7.0 it still needs the one approval described there.
+  The executor digest changes.
+
+- When the approved tasks are ready but the executor does not answer
+  (`executor_status_mismatch`), the app window offers Approve background
+  access again. With the tasks approved, it restarts the executor without
+  a password.
+
+- `executor.status` (root-ops) names approval, not "Start the package", as
+  the next step when the package's last lifecycle request was start.
+  Regenerate or copy `backend/internal/app/executor.go`.
+
+- An executor-only upgrade (same policy, new executor matching the INFO
+  `synopkgland_executor_sha256` anchor) no longer fails with "executor
+  upgrade refused: INFO-anchored executor could not be installed". The
+  installer opened `/var/packages/<pkg>/target/executor` without following
+  the DSM `target` link, which the executor refuses, so every such upgrade
+  stayed paused. The fix runs in the executor that is already installed:
+  an upgrade from a package built with an earlier SDK still needs one
+  administrator approval. The executor digest changes.
+
+- `executor.status` (root-ops and delegate projects) no longer answers
+  `internal` while the executor is paused (package stopped, or pins waiting
+  for approval). It answers `{ready: false, state: "paused", reason:
+  "executor_not_listening", next}`, and `synopkgland status` shows the
+  reason and next step. Regenerate or copy
+  `backend/internal/app/executor.go` into existing projects.
+
+- `daemon.timeouts` defaults are now `{start: 30, stop: 30, status: 5,
+  uninstall: 60}` (were `start: 5, stop: 10, status: 2`). On vt-nas under
+  IO load a boot start took more than 5 s and a Connect revoke more than
+  9 s. The new `timeouts.uninstall` (2–120) bounds `uninstall_args`
+  separately; it used to get `stop - 1`, so an app had to raise the SIGKILL
+  wait to give its revoke time. DSM's package unit allows 3600 s for start
+  and stop. `inspect` still accepts SPKs built before `timeouts.uninstall`.
+  The manifest reference explains how to pick values from a loaded NAS.
+
+### Approval, identity and uninstall fixes
+
+- `identity: standalone`: "Continue with DSM" and every live revalidation
+  failed with `session_required` after a DSM web login, because DSM web
+  sessions enable SynoToken and DSM answers the `id` cookie alone with 119.
+  The backend now forwards the request's single `X-SYNO-TOKEN` header, which
+  the DSM window's `ctx.call` already sends, when it checks the DSM session.
+  Sessions without SynoToken still verify with the cookie alone. The token is
+  never put in a URL, logged or stored. This also unblocks root-ops approval
+  in an `identity: standalone` package, which stopped at `executor.control`.
+  Existing projects need the updated `internal/identity` files.
+- When approval created and read back both tasks but the executor then did
+  not start or report healthy, the window left the tasks behind, and with no
+  running executor there was no task inventory for uninstall to delete them.
+  The window now withdraws the tasks that approval created; tasks from an
+  earlier approval stay.
+- After a wrong password or a withdrawn approval, the window panel showed
+  only "Check status". It and the app's settings now keep the approve action.
+- Uninstall no longer logs `task cleanup unconfirmed` for every successful
+  delete: EventScheduler `delete` v1 and TaskScheduler `delete` v2 answer
+  `{"success":true}` without data, which now counts as confirmed. The task
+  definitions are unchanged, so no new approval is needed; the executor
+  digest changes.
+- The native root window (`@synopackageland/cli/authorization-sdk`) gave up
+  after about 30 s with `root_timeout`, while a loaded NAS ran the bootstrap
+  task for up to 4.5 minutes. It now keeps waiting while the task is queued or
+  running, up to 10 minutes, reports `{op, state, elapsedMs}` through
+  `options.progress`, and the authorization flow accepts the backend's ready
+  grant after `root_timeout` or `root_task_failed`.
+- A DSM certificate that Node does not trust failed with only
+  `fetch failed`. The CLI now reports `DSM_TLS_UNTRUSTED` with the origin and
+  certificate error and points to `NODE_EXTRA_CA_CERTS`; certificate checks
+  stay on.
+- Docs: on DSM 7.1 the purge timing lines are only in the journal
+  (`journalctl -t synopkgland-executor`); `init -t native-go` does not include
+  `armv7` in `arches`, so add it for an armv7 NAS.
+
+### Deploy and status fixes
+
+- `status` no longer reports `blocked` for every `identity: standalone`
+  project. It opens a short-lived App session from the administrator's DSM
+  session, reads `executor.status`, then logs out. That needs an `https://`
+  host; over `http://` the capability stays `blocked` and the reason says so.
+- `deploy` accepts the install wizard values of an `install-selected`
+  delegate: `--param delegate_share=<Shared Folder>` or
+  `--param delegate_home=true`. A first install without one now fails with
+  `DEPLOY_PARAM_REQUIRED` and a usage line before anything is built, instead
+  of failing inside DSM. Invalid values fail with `DEPLOY_PARAM_TYPE_INVALID`.
+- `deploy` and `status` work on a native layout (existing native product).
+  `deploy` builds the NAS architecture only; an `aarch64` NAS uses a declared
+  `armv8`.
+- The deploy note no longer says every upgrade needs approval: an
+  executor-only upgrade stays ready; a policy digest change needs approval.
+- Uninstall logs per-phase purge timing with the package name to the system
+  log (`synopkgland-executor`): `task cleanup timing` per task and
+  `purge timing` for the task and file phases. The executor digest changes.
+- `add root-ops` and `add portal` print a notice on stderr when they raise
+  `os_min_ver`.
+- `inspect` on an executor SPK describes the root boot and control tasks
+  instead of saying the package needs no root privileges.
+
+### DSM 7.1: root-ops and delegate approval work
+
+- DSM 7.1.1 has no `SYNO.Core.TaskScheduler.Root` or
+  `SYNO.Core.EventScheduler.Root`, TaskScheduler stops at v3 and
+  PasswordConfirm at v1, so approval failed with "Background file access is
+  unavailable" and `status`/`deploy` showed `rootOps: unsupported — DSM 103`
+  or `DSM 104`. DSM 7.1.1 answers a version above the API's maximum with 104
+  (PasswordConfirm v2, TaskScheduler `get` v4) and a method missing at an
+  existing version with 103 (TaskScheduler `list` v3). When DSM answers a
+  scheduler read or the password check with 103 or 104, the app now uses
+  PasswordConfirm v1, TaskScheduler `list` v2/`get` v3 and creates
+  the tasks with EventScheduler `create` v1 and TaskScheduler `create` v3.
+  The password is still confirmed first and both tasks are still read back
+  exactly before anything runs. Other errors (such as 105, 119, 102 or a
+  wrong password, 3121) never fall back, and a create is never retried. DSM
+  7.1 does not bind task creation to the password check; see the root-ops
+  guide.
+- `status` and `deploy` read the control task the same way.
+- Uninstall on DSM 7.1 now removes the boot and control tasks. The executor
+  looked the control task up with TaskScheduler `get` v4, which DSM 7.1.1
+  refuses with 104, so it wrote no task inventory and left both tasks behind.
+- If approval stops after it created a task (for example, the boot task was
+  created and the control task was not), the app deletes the tasks it created
+  in that attempt instead of leaving an enabled root boot task that nothing
+  owns. Tasks from an earlier approval stay.
+- A failed approval shows its reason and DSM error code in the app's settings
+  instead of only "Background file access is unavailable", and a refused
+  password reads as a password failure, not a scheduler failure.
+- After the app's settings approve, the window's status line no longer shows
+  "needs-admin-approval: Task is missing" until a reload; the window panel and
+  the settings now follow each other's results.
+
+### DSM 7.1: jobs import and file downloads
+
+- DSM 7.1.1 sends `SYNO.FileStation.Download` v2 replies without
+  `Content-Disposition`, so `bg.jobs.submit` and downloads failed with
+  `unavailable`. With no such header, a body of at most 4 KiB that decodes
+  as a DSM reply is still refused as that reply; any other body is the file.
+
+### Docs: build your own armv7 Go code with Go 1.26.9
+
+- On armv7 DSM 7.1.1 (kernel 3.10), a program built with Go 1.26.0 crashed
+  at start (`futexwakeup returned -22`, SIGSEGV) and Go 1.26.9 ran. Other
+  1.26 releases were not tested.
+
+### init: next steps install frontend dependencies
+
+- `init -t native-go` with a Vue frontend now lists `(cd frontend && npm ci)`
+  before `synopkgland build`; without it the build fails with
+  `STANDALONE_UI_BUILD_FAILED`. `build` still does not install dependencies.
+
+### Executor, daemon and gateway build with exactly Go 1.26.9
+
+- The CLI builds the executor, lifecycle helper, daemon controller and gateway
+  with `GOTOOLCHAIN=go1.26.9`, ignoring your `GOTOOLCHAIN`, `GOFLAGS`,
+  `GOEXPERIMENT`, `GOWORK` and `GOAMD64`/`GOARM64`, so every builder produces
+  the same executor digest. Go 1.21 or later downloads go1.26.9 when needed;
+  offline without it the build fails and names go1.26.9. A binary whose Go
+  build info names another release is refused.
+- Template go.mod files now say `toolchain go1.26.9`. The executor digest
+  changes; it is anchored in INFO, so an upgrade with an unchanged policy needs
+  no new approval.
+
+### INFO arch: four more DSM platforms
+
+- x86_64 SPKs now also list `broadwellntb`, `coffeelake` and `skylaked`, and
+  aarch64 SPKs list `rtd1619` (DSM Developer Guide Appendix A family members).
+  INFO `arch` now matches the platforms the package source maps to each family.
+
+### 繁體中文摘要
+
+- 升級後重新建置套件；executor digest 改變。**從 0.7.0 建的套件升級需管理員再核准一次**（0.7.0 的
+  executor 開啟套件 `target` symlink 時未跟隨連結，無法自行安裝錨定的 executor）；之後 0.7.1 起的
+  executor-only 升級不需核准。
+- executor：kernel 3.10（DSM 7.1，如 DS416 armv7）上 executor-only 升級與執行中再核准不再出現
+  `pid executable mismatch`；INFO 錨定升級不再誤報 `executor upgrade refused`，也不再先印
+  「paused: 需管理員核准」；`executor.status` 暫停時回 `paused`／`executor_not_listening` 與下一步。
+- 面板：executor 不回應時可再按一次「Approve background access」免密碼重啟；
+  `executor_status_mismatch` 會寫出原因（不回應／digest 不同／status 請求失敗）；
+  啟動後的 `executor.status` 等待改為 500 ms→2 s 退避，10 s 預算不變。
+- `daemon.timeouts` 預設改為 `{start: 30, stop: 30, status: 5, uninstall: 60}`，新增 `timeouts.uninstall`。
+- `identity: standalone`：DSM 網頁 session（SynoToken）下「Continue with DSM」與 root-ops 核准修正；
+  核准建立 task 後 executor 未啟動時自動撤回本次建立的 task；卸載不再誤記 `task cleanup unconfirmed`。
+- 原生 root window 等待上限改為 10 分鐘並回報進度；`DSM_TLS_UNTRUSTED` 指向 `NODE_EXTRA_CA_CERTS`。
+- `status`／`deploy`：standalone 專案的 status 改用短期 App session；`deploy` 接受
+  install-selected delegate 的精靈參數；支援 native layout；卸載記錄 purge timing。
+- DSM 7.1：無 Root API 時改走 PasswordConfirm v1／TaskScheduler v2–v3／EventScheduler create v1，
+  卸載會移除 boot／control task；`SYNO.FileStation.Download` v2 無 `Content-Disposition` 的下載修正。
+- 建置：executor、lifecycle、daemon、gateway 一律以 Go 1.26.9 建置（armv7 kernel 3.10 上 1.26.0 會當機）；
+  INFO `arch` 新增 `broadwellntb`、`coffeelake`、`skylaked`、`rtd1619`。
+- 測試工具：`scripts/test/executor-bump.py` 收進 repo，會一併改寫視窗腳本內嵌的 executor pin。
 
 ## 0.7.0 (2026-10-10)
 

package/assets/default-icon/README.md

@@ -0,0 +1,19 @@
+# SDK default package icon
+
+Used by `synopkgland build` when `dsm-package.yaml` or `synology-app.yaml`
+sets no `icon`. It marks an App that has not chosen its own icon yet: a
+Package Land parcel on the cream brand tile, not a broken image.
+
+This folder is itself an icon directory (`icon: <dir>`): `icon_<size>.png`
+files are used as drawn and `icon_256.png` is scaled for any missing size.
+
+- `default-icon.svg` draws 48, 64, 72 and 256.
+- `default-icon-small.svg` is a 16 px pixel grid for 16, 24 and 32.
+
+Regenerate after editing an SVG (rsvg-convert is a maintainer tool only;
+the CLI never rasterises SVG):
+
+```sh
+for s in 16 24 32; do rsvg-convert -w $s -h $s default-icon-small.svg -o icon_$s.png; done
+for s in 48 64 72 256; do rsvg-convert -w $s -h $s default-icon.svg -o icon_$s.png; done
+```

package/assets/default-icon/default-icon-small.svg

@@ -0,0 +1,9 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" viewBox="0 0 16 16" shape-rendering="crispEdges">
+  <rect x="0" y="0" width="16" height="16" rx="3.5" fill="#fbf5e8"/>
+  <rect x="3" y="2" width="2" height="2" fill="#1f78e5"/>
+  <rect x="7" y="1" width="2" height="3" fill="#f6b324"/>
+  <rect x="11" y="2" width="2" height="2" fill="#1f78e5"/>
+  <rect x="2" y="4" width="12" height="3" fill="#135bb8"/>
+  <rect x="3" y="7" width="10" height="7" fill="#1f78e5"/>
+  <rect x="6" y="9" width="4" height="1" fill="#fbf5e8"/>
+</svg>

package/assets/default-icon/default-icon.svg

@@ -0,0 +1,10 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="256" height="256" viewBox="0 0 256 256">
+  <rect x="6" y="6" width="244" height="244" rx="56" fill="#fbf5e8" stroke="#e4d8bd" stroke-width="4"/>
+  <path d="M212 22l6 14 14 6-14 6-6 14-6-14-14-6 14-6z" fill="#f6b324"/>
+  <rect x="62" y="58" width="30" height="30" rx="6" fill="#1f78e5"/>
+  <rect x="113" y="50" width="30" height="38" rx="6" fill="#f6b324"/>
+  <rect x="164" y="58" width="30" height="30" rx="6" fill="#1f78e5"/>
+  <rect x="48" y="80" width="160" height="44" rx="12" fill="#135bb8"/>
+  <path d="M58 118h140v66a24 24 0 0 1-24 24H82a24 24 0 0 1-24-24z" fill="#1f78e5"/>
+  <rect x="100" y="140" width="56" height="16" rx="8" fill="#fbf5e8"/>
+</svg>

package/dist/add.d.ts

@@ -1,4 +1,7 @@
-export declare function addCapabilities(root: string, requested: string[]): {
+type AddResult = {
     added: string[];
     unchanged: string[];
+    notes?: string[];
 };
+export declare function addCapabilities(root: string, requested: string[]): AddResult;
+export {};

package/dist/add.js

@@ -46,11 +46,17 @@ function safePath(root, file) {
     }
     return true;
 }
-/** Raise a lower os_min_ver to the floor a capability needs; a higher one stays. */
-function raiseOsMinVer(doc, current, floor) {
+/** Raise a lower os_min_ver to the floor a capability needs; a higher one stays. Returns the notice. */
+function raiseOsMinVer(doc, current, floor, capability) {
     const osMinVer = doc.get('os_min_ver', true);
-    if (isScalar(osMinVer) && !isDsmAtLeast(current, floor))
-        osMinVer.value = floor;
+    if (!isScalar(osMinVer) || isDsmAtLeast(current, floor))
+        return [];
+    osMinVer.value = floor;
+    return [`os_min_ver raised from ${current} to ${floor}: ${capability} needs DSM ${floor} or later.`];
+}
+function withNotes(result, notes) {
+    const all = [...(result.notes ?? []), ...notes];
+    return all.length ? { ...result, notes: all } : result;
 }
 /**
  * `portal: {}` in dsm-package.yaml; the Go and binary starters already carry the UI and backend side.
@@ -67,9 +73,9 @@ function addPortal(root, result) {
     const manifestPath = join(root, 'dsm-package.yaml');
     const doc = parseDocument(readFileSync(manifestPath, 'utf8'));
     doc.set('portal', doc.createNode({}, { flow: true }));
-    raiseOsMinVer(doc, loaded.manifest.os_min_ver, PORTAL_MIN_DSM);
+    const notes = raiseOsMinVer(doc, loaded.manifest.os_min_ver, PORTAL_MIN_DSM, 'portal');
     writeFileSync(manifestPath, String(doc));
-    return { ...result, added: [...result.added, 'portal'] };
+    return withNotes({ ...result, added: [...result.added, 'portal'] }, notes);
 }
 export function addCapabilities(root, requested) {
     const wanted = [...new Set(requested.flatMap(value => value.split(',')).map(value => value.trim()))];
@@ -129,8 +135,7 @@ export function addCapabilities(root, requested) {
         for (const [key, value] of Object.entries(nativeCapabilitySettings(added)))
             doc.setIn(['capabilities', key], value);
         // rootOps needs DSM 7.1-42661 or later.
-        if (added.includes('root-ops'))
-            raiseOsMinVer(doc, m.os_min_ver, DEFAULT_MIN_DSM);
+        const notes = added.includes('root-ops') ? raiseOsMinVer(doc, m.os_min_ver, DEFAULT_MIN_DSM, 'root-ops') : [];
         for (const file of destinations) {
             const path = join(root, file);
             mkdirSync(dirname(path), { recursive: true });
@@ -139,7 +144,7 @@ export function addCapabilities(root, requested) {
         for (const file of deletions)
             rmSync(join(root, file), { force: true });
         writeFileSync(manifestPath, String(doc));
-        return { added, unchanged };
+        return withNotes({ added, unchanged }, notes);
     }
     finally {
         rmSync(work, { recursive: true, force: true });

package/dist/build-spk/dsm-icons.d.ts

@@ -1,2 +1,31 @@
-export declare function writeDsmWindowIcons(uiDir: string): void;
-export declare function writePackageCenterIcons(spkRoot: string): void;
+/** Sizes DSM loads for `images/app_{0}.png` (main menu, desktop, window, taskbar). */
+export declare const WINDOW_ICON_SIZES: readonly [16, 24, 32, 48, 64, 72, 256];
+/** The package source drops a release whose PACKAGE_ICON is larger than this. */
+export declare const MAX_ICON_BYTES: number;
+export interface PackageIcons {
+    source: "custom" | "default";
+    /** Encoded PNG per DSM window size; PACKAGE_ICON.PNG is 64 and PACKAGE_ICON_256.PNG is 256. */
+    window: Map<number, Buffer>;
+    packageIcon: Buffer;
+    packageIcon256: Buffer;
+    /** Every pixel of the 256 px icon is the same colour. */
+    solid: boolean;
+}
+/** Ships next to dist/ and src/ alike: <package>/assets/default-icon. */
+export declare const DEFAULT_ICON_DIR: string;
+/** A project icon: one square PNG of at least 256 px, or a directory of icon_<size>.png. */
+export declare function renderPackageIcons(path: string): PackageIcons;
+/** The SDK default icon, for projects that set no `icon`. */
+export declare function defaultPackageIcons(): PackageIcons;
+/** The project's icon when it sets one, otherwise the SDK default. */
+export declare function packageIcons(icon: string | undefined): PackageIcons;
+/** What check reports: which icon a build would use, relative to the project. */
+export interface IconReport {
+    /** `layout`: a native layout without `icon`, whose metadata owns PACKAGE_ICON*.PNG. */
+    source: PackageIcons["source"] | "layout";
+    path?: string;
+    solid: boolean;
+}
+export declare function iconReport(root: string, icon: string | undefined): IconReport;
+export declare function writeDsmWindowIcons(uiDir: string, icons: PackageIcons): void;
+export declare function writePackageCenterIcons(spkRoot: string, icons: PackageIcons): void;