Skip to content

fix(plugin-devkit): reject package-relative theme assets at check time - #944

Merged
vastsa merged 1 commit into
vastsa:mainfrom
VMF-HIBIKI:fix/devkit-theme-asset-absolute-only
Sep 23, 2026
Merged

vastsa merged 1 commit into
vastsa:mainfrom
VMF-HIBIKI:fix/devkit-theme-asset-absolute-only

Conversation

@VMF-HIBIKI

Copy link
Copy Markdown

Summary

pi-plugin check now fails contributes.themes[].assets entries that the host-core installer rejects, with a message that names the migration path. Fixes #943 (direction A, author-time half).

Problem

ADR 0255 made theme assets absolute filesystem paths and the host-core installer enforces it. The SDK validator (isThemeAssetPath), the SDK doc comments ("may be package-relative or absolute"), and the PluginThemeContrib.assets doc still accept the package-relative spelling, so a theme plugin can pass pi-plugin check, publish to a catalog, and then fail installation for every user with an error that reads like a plugin bug:

PLUGIN_INVALID: theme cyber-diva asset themes/assets/wallpaper-dark.webp must be an absolute image or font path

An absolute spelling is not an escape hatch for a distributed package either: the installer requires the referenced file to already exist on the installing machine (asset missing), so package-shipped bytes have no installable manifest spelling at all (see #943 for the full matrix).

Impact

  • Catalog theme plugins that follow the SDK documentation are uninstallable for every user (case: local.miku-theme 1.0.0 in AIUO-Net/pi-desktop-plugins, review-approved, pi-plugin check-clean).
  • The failure surfaces at install time on end-user machines, far from the author, with no migration hint.

Change

packages/plugin-devkit/src/check.ts gains one check after validateManifest: for every contributes.themes[].assets entry whose normalized form is valid but not external (normalizeThemeAssetPath + isExternalThemeAssetPath, both already exported by the SDK), it reports theme.asset-package-relative with the ADR 0255 rule and the two migration routes (bytes in pi.plugin.getDataPath() referenced by absolute path, or runtime registration via pi.themes.upsert).

Deliberately scoped:

Affected ADRs / specs

Validation

pnpm --filter @pi-desktop/plugin-devkit test        → 49 passed (49), incl. the new case
pnpm --filter @pi-desktop/plugin-devkit typecheck   → clean
node scripts/check-pr-base-main.mjs                 → PR base check passed: head a634b687706c is the base

New test fails theme assets the installer rejects: package-relative paths (ADR 0255) covers: package-relative asset → error quoting the asset, the absolute-path rule, and pi.themes.upsert; absolute spelling → check stays green.

E2E: NOT RUN — this change is confined to the devkit CLI's static checks (pi-plugin check) and has no runtime surface in the desktop app; unit coverage exercises both outcomes directly. Remaining risk is limited to the wording of the new diagnostic.

Compatibility / migration

  • Authors with package-relative assets now get a hard error from pi-plugin check before publishing; the message states where the bytes must live. That is the intended ADR 0255 behavior arriving at author time instead of at users' install time.
  • Already-published packages and locally installed plugins are unaffected by this PR.

ADR 0255 made theme assets absolute filesystem paths and the host-core
installer enforces it, but validateManifest in the SDK still accepts the
package-relative spelling, so a theme plugin can pass pi-plugin check and
be published while no user can install it:

  PLUGIN_INVALID: theme <id> asset themes/assets/wallpaper-dark.webp must
  be an absolute image or font path

Fail the check with a actionable message that points at the migration
path (ship bytes in pi.plugin.getDataPath() and reference them by
absolute path, or register them at runtime with pi.themes.upsert).

The shared SDK normalizer and the runtime loader keep accepting
package-relative references for already-installed plugins; whether the
loader should enforce ADR 0255 as well is left to the linked issue.
@vastsa
vastsa merged commit 0af2339 into vastsa:main Sep 23, 2026
vastsa added a commit that referenced this pull request Sep 23, 2026
- ADR 0255: mention devkit author-time check (#944)
- 08-component-spec: cross-reference SVG file-only classification (#969)
- e2e-test-plan: register E2E-ATTACHMENTS-svg-file-fallback scenario (#969)
- zh-CN 08-component-spec: mirror SVG exclusion rule (#969)
- zh-CN 09-interaction-patterns: add §3.4 queued send with promoted-row
  cancel semantics (#965)
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[Bug] Theme plugins with package-relative assets pass pi-plugin check but cannot be installed (SDK/loader vs installer disagree after ADR 0255)

2 participants