lecodes-cli 0.19.0 → 0.20.0

package/src/commands/appShared.ts

@@ -0,0 +1,542 @@
+import { execFileSync } from "node:child_process"
+import { existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from "node:fs"
+import { homedir } from "node:os"
+import { dirname, join, resolve } from "node:path"
+import { findProjectRoot } from "../manifest"
+import { DEFAULT_IGNORE_FILE } from "../ignore"
+import { CliError, c, flagStr, log, note, warn, type Args } from "../util"
+
+/* Shared plumbing for the `lecodes app` platform arms (app.ts = iOS + dispatch,
+ * appAndroid.ts = Android). Everything here moved verbatim out of app.ts when the Android
+ * arm landed — behavior for iOS is unchanged; the SDK helpers just grew a repo parameter
+ * (lecodes-ios-sdk vs lecodes-android-sdk) and resolvePlugin a platform one. */
+
+/** First-party plugin registry: id → GitHub repo holding plugins/<id>/. Third-party plugins
+ *  use a `github:owner/repo[@tag]` spec in app.json instead (manifest at the repo root). */
+export const FIRST_PARTY_PLUGINS: Record<string, string> = {
+  "camera": "letary/lecodes-plugins",
+  "qr-scanner": "letary/lecodes-plugins",
+  "map": "letary/lecodes-plugins",
+  "geolocation": "letary/lecodes-plugins",
+  "push": "letary/lecodes-plugins",
+}
+
+export interface AppConfig {
+  name?: string
+  version?: string
+  /** Project-root-relative path of a square ≥1024px PNG/JPEG master. When set, every sync
+   *  renders the platform icons from it (iOS AppIcon + Android adaptive/legacy mipmaps) and
+   *  those files become CLI-owned like assets/. Absent = icons stay hand-managed; removing
+   *  the key stops regeneration but deletes nothing. */
+  icon?: string
+  /** Icon backdrop ("#RGB"/"#RRGGBB", default white): the Android adaptive-icon background
+   *  layer, and what a transparent master is flattened onto for the opacity-required iOS icon. */
+  iconBackground?: string
+  plugins?: Record<string, string>
+  /** `remote`: lecodesignore-style globs of resources to STREAM from the server instead of
+   *  embedding in the app (server-backed projects only — a streamed asset needs a server URL). */
+  resources?: { remote?: string[] }
+  /** Over-the-air JS updates: where the shell checks for newer compiled code at launch
+   *  (natively, before the JS engine — offline is a no-op, new code applies next launch).
+   *  `true` = this project's live bundle on the platform (server-backed only); or an https
+   *  URL to a compiled bundle on any hosting (string or `{ "url": … }`). Absent = no OTA.
+   *  iOS-only for now — the Android runtime has no native updater yet. */
+  update?: boolean | string | { url?: string }
+  /** `variant`: SDK product — "auto" (default: sync picks the smallest one covering the engines
+   *  the compiled bundle actually uses) or core|2d|3d|full to force one.
+   *  `sdk`: native SDK version — an exact lecodes-ios-sdk release (init pins the newest one,
+   *  `lecodes app update` moves it), or "latest" to re-resolve on every sync. */
+  ios?: { bundleId?: string, teamId?: string, variant?: string, buildNumber?: number, sdk?: string }
+  /** `applicationId`: the Android package name (init default: com.example.<slug>).
+   *  `versionCode`: Play's monotonically increasing build number (versionName comes from the
+   *  shared `version`). `sdk`: an exact lecodes-android-sdk release or "latest", like ios.sdk.
+   *  `variant`: SDK artifact — "auto" (default: sync picks the smallest one covering the engines
+   *  the compiled bundle actually uses) or core|2d|3d|full to force one, like ios.variant
+   *  (needs lecodes-android-sdk >= 1.3.0 — older releases ship only the full AAR).
+   *  `signing`: keystore METADATA only — the store/key passwords live in android/
+   *  keystore.properties (gitignored) or LECODES_ANDROID_* env vars, never in app.json. */
+  android?: {
+    applicationId?: string, versionCode?: number, sdk?: string, variant?: string,
+    signing?: { storeFile?: string, keyAlias?: string },
+  }
+  /** Desktop host (packages/desktop). `window` sizes are LOGICAL units — the host multiplies by
+   *  the display scale. `entry` picks a per-target entry file (default: the detected project
+   *  entry) — see docs/desktop-target-plan.md. */
+  desktop?: {
+    entry?: string,
+    window?: DesktopWindowConfig,
+    /** Which desktop host binary to run: "gl" (default) or "vulkan" (Windows only, host >= 1.4.0).
+     *  A BUILD/DEV-TIME host selection, not a runtime switch — the two are separate binaries with
+     *  their own shaders and different features (the Vulkan one has no 2D engine and no native-view
+     *  plugins). Overridable per run with `--renderer` / LECODES_DESKTOP_RENDERER. */
+    renderer?: "gl" | "vulkan",
+    /** 3D buffer scale vs the window (0.25–1, host ≥1.4.0). The UI always renders at native
+     *  pixels; only the 3D scene is rendered smaller and upscaled by the compositor. Multiplies
+     *  the scene's own `renderScale` (SceneOptions). Headless render/test ignore it. */
+    renderScale?: number,
+    /** 3D buffer cap in px, e.g. [1920, 1080]: on a bigger window/monitor the 3D renders at most
+     *  this size (aspect kept) — the per-machine answer to "fullscreen on a 4K display is slow". */
+    maxRenderSize?: [number, number],
+    /** The macOS .app build (`lecodes app build desktop` on a Mac) — identity + signing +
+     *  notarization. See appDesktopMac.ts for the whole story. */
+    macos?: MacDesktopConfig,
+  }
+}
+
+/** app.json `desktop.macos`. Only NAMES live here (identity, keychain profile) — the certificate
+ *  and the notarization password stay in the keychain. */
+export interface MacDesktopConfig {
+  /** CFBundleIdentifier (default codes.le.app.<slug>). Reverse-DNS, stable across releases. */
+  bundleId?: string
+  /** CFBundleVersion (default 1). Bump per upload; the top-level `version` is the marketing one. */
+  buildNumber?: number
+  /** LSApplicationCategoryType, e.g. "public.app-category.games". */
+  category?: string
+  /** `identity`: a "Developer ID Application: Name (TEAM)" codesign identity, or "adhoc" (local
+   *  only — refused on every other Mac). Absent/"auto": the keychain's Developer ID cert, else
+   *  ad-hoc. Overridden by --sign / LECODES_MACOS_SIGN_ID. */
+  signing?: { identity?: string }
+  /** `profile`: a `xcrun notarytool store-credentials <name>` keychain profile. With it the build
+   *  is notarized + stapled (needs a Developer ID identity). Overridden by --notarize /
+   *  LECODES_NOTARY_PROFILE; --no-notarize skips for a local build. */
+  notarize?: { profile?: string }
+}
+
+export interface DesktopWindowConfig {
+  /** Initial client size, logical units (host default: 1280×720). */
+  width?: number
+  height?: number
+  minWidth?: number
+  minHeight?: number
+  /** false → fixed-size window (default: resizable). */
+  resizable?: boolean
+  /** Window title (default: the top-level `name`). */
+  title?: string
+  /** Borderless fullscreen on the primary monitor (kiosks). `width`/`height` stay the
+   *  design/dev frame; headless render/test always run windowed (the render contract). */
+  fullscreen?: boolean
+  /** Display scale (host ≥1.3.0). "system" (default): the OS display scale. A number (0.5–4):
+   *  a fixed density — the window opens at `width×scale` physical px. "fit": derived at launch
+   *  from the design frame vs the monitor (fullscreen) / work area, so a 1080p-designed app
+   *  runs density-2 on a 4K display and scales DOWN on smaller screens. Headless render/test
+   *  always force scale 1 (the render contract). */
+  scale?: number | "fit" | "system"
+}
+
+/** app.json wherever a command needs the project-level desktop/window config. Tolerant of a
+ *  missing or broken file — standalone projects (no app.json) must keep working everywhere
+ *  this is consulted. */
+export const readAppConfigAt = (root: string): AppConfig | null =>
+  readJson<AppConfig>(join(root, "app.json"))
+
+/** The desktop host's own built-in fallback, mirrored where the CLI must fill a missing side. */
+export const DESKTOP_DEFAULT_WINDOW = { width: 1280, height: 720 }
+
+/**
+ * The renderer for this run: `--renderer` > LECODES_DESKTOP_RENDERER > app.json `desktop.renderer`
+ * > "gl". Resolve it ONCE per command and pass the result to both `resolveDesktopExe` and the
+ * shader staging — two independent reads of the config is how a build ends up with a Vulkan exe
+ * next to an OpenGL .filamat, which fails at the first material with a Filament abort.
+ */
+export const resolveDesktopRenderer = (root: string, args?: Args): "gl" | "vulkan" => {
+  const raw = (args ? flagStr(args, "renderer") : undefined)
+    ?? process.env.LECODES_DESKTOP_RENDERER
+    ?? readAppConfigAt(root)?.desktop?.renderer
+  if (raw === undefined) return "gl"
+  const value = String(raw).toLowerCase()
+  if (value === "gl" || value === "opengl") return "gl"
+  if (value === "vulkan" || value === "vk") {
+    // The macOS host is Metal, full stop. A project tuned for the Windows Vulkan host must still
+    // build/run on a Mac, so the setting is a no-op here rather than an error.
+    if (process.platform === "darwin") { note("desktop.renderer \"vulkan\" is Windows-only — the macOS host renders with Metal."); return "gl" }
+    return "vulkan"
+  }
+  throw new CliError(`Unknown desktop renderer "${raw}". Use "gl" or "vulkan".`)
+}
+
+/** Project-level default viewport for HEADLESS render/test: the desktop window when the project
+ *  declares desktop as its ONLY native target (a desktop-only project gets desktop-sized frames
+ *  and flow tests for free). Mixed or mobile projects keep the phone default — headless frames
+ *  exercise the phone UI there. */
+export const desktopDefaultViewport = (root: string): { width: number, height: number } | null => {
+  const cfg = readAppConfigAt(root)
+  if (!cfg?.desktop || cfg.ios || cfg.android) return null
+  return {
+    width: cfg.desktop.window?.width ?? DESKTOP_DEFAULT_WINDOW.width,
+    height: cfg.desktop.window?.height ?? DESKTOP_DEFAULT_WINDOW.height,
+  }
+}
+
+/** A SwiftPM dependency a plugin's iOS target links (manifest ios.packages). */
+export interface IosPackage {
+  url: string
+  /** Pinned release — the normal case (a plugin's sources compile against one API). */
+  exact?: string
+  /** Minimum release, SwiftPM picks the newest compatible major. Exclusive with `exact`. */
+  from?: string
+  /** Library products of that package the plugin target imports. */
+  products: string[]
+}
+
+/** SwiftPM's package identity for a url: the last path segment without `.git`. */
+export const swiftPackageName = (url: string): string =>
+  (url.replace(/\/+$/, "").split("/").pop() ?? url).replace(/\.git$/, "")
+
+export interface PluginManifest {
+  id: string
+  version?: string
+  provides?: { views?: string[], services?: string[] }
+  ios?: {
+    sources?: string, module?: string, register?: string, minSdk?: string,
+    infoPlist?: Record<string, string>,
+    /** Entitlements the plugin's capability needs (plist-typed JSON values, arrays allowed —
+     *  e.g. push's `{"aps-environment": "development"}`). Merged into App/App.entitlements
+     *  by sync; the relay signs sends for Letary-published bundle ids with the shared team
+     *  key, and the register route fail-fasts for anything outside that namespace. */
+    entitlements?: Record<string, unknown>,
+    /** Swift packages the vendored target links (e.g. the map plugin's maplibre-native). Each
+     *  becomes a `.package(url:…)` in the generated LeCodesRuntime/Package.swift (exact or
+     *  from — one of the two) and its `products` become `.product(name:package:)` deps of the
+     *  plugin target. The package name is the URL's last path segment minus `.git`, as SwiftPM
+     *  derives it. Two plugins naming the same url must agree on the version. */
+    packages?: IosPackage[],
+  } | null
+  android?: {
+    /** Dir vendored into the shell (default "android") — a Gradle-module-shaped tree minus
+     *  build.gradle (sync generates that): src/main/AndroidManifest.xml carries the plugin's
+     *  permissions/services (AGP's manifest merger is the infoPlist analog), libs/*.aar become
+     *  local file deps, consumer-rules.pro becomes the module's consumer ProGuard rules. */
+    sources?: string,
+    /** Gradle module name (kebab-case) → :plugins:<module> in the shell. */
+    module?: string,
+    /** Fully-qualified Kotlin object with `fun register(engine: LecodesEngine, context: Context)`;
+     *  its package doubles as the generated module's AGP namespace. */
+    register?: string,
+    /** Minimum lecodes-android-sdk release (NOT Android's minSdkVersion — the OS floor comes
+     *  from the SDK itself). Sync hard-errors below it, like ios.minSdk. */
+    minSdk?: string,
+    /** Maven coordinates for the generated build.gradle. A "platform:" prefix maps to
+     *  implementation(platform(…)) — BoMs; versionless coords are only valid under one. */
+    dependencies?: string[],
+    /** App-level Gradle plugin ids the shell must apply (e.g. com.google.gms.google-services).
+     *  Bare ids resolve through the CLI's known-version table; "id:version" pins explicitly. */
+    gradlePlugins?: string[],
+  } | null
+  /** Desktop host (packages/desktop): a PREBUILT shared library per OS/arch behind the C ABI in
+   *  `packages/desktop/plugin-sdk/lecodes_plugin.h` — no host rebuild, no source vendoring.
+   *  `library` keys are `${process.platform}-${process.arch}` ("win32-x64", "linux-x64",
+   *  "linux-arm64"), values plugin-dir-relative paths. `lecodes desktop run` / `render --desktop`
+   *  forward the library's dir to the host (CREATOR_PLUGIN_DIRS); `app build desktop` stages the
+   *  file into `<build>/plugins/`. A plugin without a build for the current target is skipped. */
+  desktop?: {
+    library?: Record<string, string>,
+  } | null
+}
+
+export interface LockEntry { repo: string, tag: string, commit: string, version: string }
+
+export const readJson = <T>(path: string): T | null => {
+  if (!existsSync(path)) return null
+  // BOM-tolerant: Notepad and PowerShell write UTF-8 with a BOM, and app.json is hand-edited.
+  try { return JSON.parse(readFileSync(path, "utf8").replace(/^\uFEFF/, "")) as T } catch {
+    throw new CliError(`Invalid JSON in ${path}`)
+  }
+}
+
+export const writeJson = (path: string, value: unknown) =>
+  writeFileSync(path, JSON.stringify(value, null, 2) + "\n")
+
+export const projectRoot = (): string => {
+  try { return findProjectRoot(process.cwd()) } catch { return process.cwd() }
+}
+
+export const git = (cwd: string, ...args: string[]): string =>
+  execFileSync("git", args, { cwd, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] }).trim()
+
+export const slugify = (s: string) => s.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "") || "app"
+
+/** Run a tool, capturing output; on failure surface the tail (xcodebuild/gradle logs are huge). */
+export const runTool = (cwd: string, cmd: string, args: string[]): string => {
+  try {
+    return execFileSync(cmd, args, { cwd, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], maxBuffer: 128 * 1024 * 1024 })
+  } catch (e) {
+    const err = e as { stdout?: string, stderr?: string }
+    const tail = ((err.stdout ?? "") + "\n" + (err.stderr ?? "")).split("\n").filter(l => l.trim()).slice(-25).join("\n")
+    throw new CliError(`${cmd} ${args[0] ?? ""} failed:\n${tail}`)
+  }
+}
+
+/** Add a shell dir (ios/, android/) to .lecodesignore — shells are never pushed to LeCodes. */
+export const ensureShellIgnored = (root: string, dir: string) => {
+  const ignorePath = join(root, ".lecodesignore")
+  const ignore = existsSync(ignorePath) ? readFileSync(ignorePath, "utf8") : DEFAULT_IGNORE_FILE
+  if (new RegExp(`^${dir}\\/$`, "m").test(ignore)) return
+  const comment = ignore.includes("# Native app shells")
+    ? ""
+    : "# Native app shells — generated by `lecodes app init`, never pushed to LeCodes.\n"
+  writeFileSync(ignorePath, ignore.replace(/\n*$/, "\n") + "\n" + comment + `${dir}/\n`)
+  log(`${c.green("updated")}   .lecodesignore  (+ ${dir}/)`)
+}
+
+/* ----------------------------------- SDK variants ----------------------------------- */
+
+// Both native SDKs ship the same variant matrix (full / 3d / 2d / core), so the detection and
+// resolution logic is shared between the iOS (app.ts) and Android (appAndroid.ts) syncs.
+export const SDK_VARIANTS = ["core", "2d", "3d", "full"] as const
+type SdkVariantShared = (typeof SDK_VARIANTS)[number]
+
+/** Engine signals from a compiled bundle's header — the same lines buildHeader emits.
+ *  No `// gl: disable` line → the 3D engine is used (eagerly, or lazily via `gl: defer`);
+ *  `// 2d: enable` → the 2D engine is used. */
+export const detectEngines = (bundleJs: string): { gl: boolean, g2: boolean } => {
+  const lines: string[] = []
+  for (const line of bundleJs.split("\n")) {
+    if (!line.startsWith("//")) break
+    lines.push(line)
+  }
+  const header = lines.join("\n")
+  return { gl: !/^\/\/ gl: disable$/m.test(header), g2: /^\/\/ 2d: enable$/m.test(header) }
+}
+
+/**
+ * Refuse a Vulkan desktop build for a project that uses the 2D engine. The Vulkan host is built with
+ * CREATOR_PKG_2D=OFF (creator-2d is sokol-on-GL, with no Vulkan twin), so those scenes don't render
+ * — a blank window at runtime with nothing in the log to explain it. Fail at build time instead,
+ * where the fix ("use the default renderer") is one line away.
+ *
+ * Detection is the same `// 2d: enable` bundle header `lecodes app sync` picks its SDK variant from,
+ * so it can't drift from what the engine actually needs.
+ */
+export const assertRendererSupportsBundle = (renderer: "gl" | "vulkan", bundleJs: string): void => {
+  if (renderer !== "vulkan") return
+  if (!detectEngines(bundleJs).g2) return
+  throw new CliError(
+    "This project uses the 2D engine, which the Vulkan desktop host doesn't include " +
+    "(creator-2d renders through OpenGL and has no Vulkan path yet).\n" +
+    "  Build with the default renderer: drop `desktop.renderer` from app.json, or pass `--renderer gl`.",
+  )
+}
+
+/** The SDK product for a shell: the smallest variant covering the engines the compiled bundle
+ *  actually uses, unless <configKey> (ios.variant / android.variant) forces one — then warn when
+ *  the forced product can't run the project (missing engine = those scenes silently no-op on
+ *  device). */
+export const resolveVariant = (requested: string, bundleJs: string, configKey = "ios.variant"): { variant: SdkVariantShared, detected: SdkVariantShared } => {
+  const uses = detectEngines(bundleJs)
+  const detected: SdkVariantShared = uses.gl && uses.g2 ? "full" : uses.gl ? "3d" : uses.g2 ? "2d" : "core"
+  if (requested === "auto") return { variant: detected, detected }
+  const variant = requested as SdkVariantShared
+  const missing = [
+    uses.gl && variant !== "3d" && variant !== "full" ? "3D" : null,
+    uses.g2 && variant !== "2d" && variant !== "full" ? "2D" : null,
+  ].filter(Boolean)
+  if (missing.length > 0) {
+    warn(`project uses the ${missing.join(" + ")} engine but ${configKey} forces "${variant}" — those scenes won't run on device; remove ${configKey} to auto-select "${detected}".`)
+  }
+  return { variant, detected }
+}
+
+/* ----------------------------------- SDK version ------------------------------------ */
+
+export const VERSION_RE = /^\d+\.\d+\.\d+$/
+
+/** Numeric semver-ish compare (only x.y.z tags are published). */
+export const cmpVersion = (a: string, b: string): number => {
+  const pa = a.split(".").map(Number)
+  const pb = b.split(".").map(Number)
+  for (let i = 0; i < 3; i++) {
+    if ((pa[i] ?? 0) !== (pb[i] ?? 0)) return (pa[i] ?? 0) - (pb[i] ?? 0)
+  }
+  return 0
+}
+
+/** The newest published release of an SDK dist repo (prereleases excluded). Network — throws. */
+export const fetchLatestSdkVersion = async (repo: string): Promise<string> => {
+  const url = `https://api.github.com/repos/${repo}/releases/latest`
+  const res = await fetch(url, { headers: { "accept": "application/vnd.github+json", "user-agent": "lecodes-cli" } })
+  if (!res.ok) throw new CliError(`Could not read the latest ${repo} release (HTTP ${res.status}) — ${url}`)
+  const tag = ((await res.json()) as { tag_name?: string }).tag_name?.replace(/^v/, "") ?? ""
+  if (!VERSION_RE.test(tag)) throw new CliError(`${repo} latest release has no x.y.z tag (got "${tag}")`)
+  return tag
+}
+
+/** Resolve an app.json sdk value ("latest" or an exact release) to the concrete release the
+ *  shell links; `fallback` is what "latest" degrades to when the network is unavailable. */
+export const resolveSdkVersion = async (
+  pin: string, fallback: string | null,
+  opts: { repo: string, minVersion: string, configKey: string },
+): Promise<string> => {
+  if (pin !== "latest") {
+    if (!VERSION_RE.test(pin)) {
+      throw new CliError(`app.json ${opts.configKey} must be "latest" or an exact x.y.z release (got "${pin}").`)
+    }
+    if (cmpVersion(pin, opts.minVersion) < 0) {
+      throw new CliError(`app.json ${opts.configKey} ${pin} is older than the ${opts.minVersion} these generated shells need.`)
+    }
+    return pin
+  }
+  try {
+    return await fetchLatestSdkVersion(opts.repo)
+  } catch (e) {
+    const kept = fallback ?? opts.minVersion
+    warn(`Could not resolve the latest SDK (${(e as Error).message}) — staying on ${kept}.`)
+    return kept
+  }
+}
+
+/* ---------------------------------- plugin vendoring ---------------------------------- */
+
+export interface ResolvedPlugin {
+  id: string
+  dir: string            // directory containing lecodes-plugin.json
+  manifest: PluginManifest
+  lock: LockEntry
+}
+
+/** Clone-or-update the plugin repo cache and check out the wanted commit (detached).
+ *  `LECODES_PLUGINS_DIR` overrides with a local working tree — the plugin-development loop. */
+export const ensureRepo = (repo: string, wantTag: string | null, lock: LockEntry | undefined): { dir: string, tag: string, commit: string } => {
+  const override = process.env.LECODES_PLUGINS_DIR
+  if (override) {
+    note(`Using local plugin checkout ${override} (LECODES_PLUGINS_DIR)`)
+    return { dir: resolve(override), tag: "local", commit: "local" }
+  }
+
+  const cache = join(homedir(), ".lecodes", "plugins", repo.replace("/", "__"))
+  const url = `https://github.com/${repo}.git`
+  if (!existsSync(join(cache, ".git"))) {
+    mkdirSync(dirname(cache), { recursive: true })
+    note(`Cloning ${url}…`)
+    git(dirname(cache), "clone", "--quiet", url, cache)
+  }
+
+  // A lock pin wins; else an explicit @tag; else the latest v* tag (fetched fresh).
+  let tag = lock?.tag ?? wantTag
+  let commit = lock?.commit
+  if (commit) {
+    try { git(cache, "cat-file", "-e", `${commit}^{commit}`) } catch {
+      git(cache, "fetch", "--quiet", "--tags", "origin")
+    }
+  } else {
+    git(cache, "fetch", "--quiet", "--tags", "origin")
+    if (!tag) {
+      tag = git(cache, "tag", "--list", "v*", "--sort=-version:refname").split("\n")[0] ?? ""
+      if (!tag) throw new CliError(`${repo} has no v* version tags to install from`)
+    }
+    commit = git(cache, "rev-list", "-n", "1", tag)
+  }
+  git(cache, "checkout", "--quiet", "--detach", commit)
+  return { dir: cache, tag: tag ?? "unknown", commit }
+}
+
+/** Resolve one app.json plugin entry to vendorable sources + manifest + lock pin. The platform
+ *  being synced must be supported (its manifest branch non-null) — a hard error otherwise. */
+export type PluginPlatform = "ios" | "android" | "desktop"
+const PLUGIN_PLATFORM_LABEL: Record<PluginPlatform, string> = { ios: "iOS", android: "Android", desktop: "desktop" }
+
+export function resolvePlugin(id: string, spec: string, lock: LockEntry | undefined, platform: PluginPlatform): ResolvedPlugin
+export function resolvePlugin(id: string, spec: string, lock: LockEntry | undefined, platform: PluginPlatform, opts: { optional: true }): ResolvedPlugin | null
+export function resolvePlugin(id: string, spec: string, lock: LockEntry | undefined, platform: PluginPlatform, opts?: { optional?: boolean }): ResolvedPlugin | null {
+  let repo: string
+  let subdir: string
+  let wantTag: string | null = null
+
+  if (spec.startsWith("github:")) {
+    const [repoPart, tagPart] = spec.slice("github:".length).split("@")
+    repo = repoPart
+    wantTag = tagPart ?? null
+    subdir = ""                                   // third-party: manifest at the repo root
+  } else {
+    repo = FIRST_PARTY_PLUGINS[id]
+    if (!repo) {
+      throw new CliError(`Unknown plugin "${id}" — known: ${Object.keys(FIRST_PARTY_PLUGINS).join(", ")}, or use a github:owner/repo spec.`)
+    }
+    subdir = `plugins/${id}`
+  }
+
+  const checkout = ensureRepo(repo, wantTag, lock?.repo === repo ? lock : undefined)
+  const dir = subdir ? join(checkout.dir, subdir) : checkout.dir
+  const manifest = readJson<PluginManifest>(join(dir, "lecodes-plugin.json"))
+  if (!manifest) throw new CliError(`Plugin "${id}": no lecodes-plugin.json in ${dir}`)
+  if (manifest.id !== id) throw new CliError(`Plugin "${id}": manifest declares id "${manifest.id}"`)
+  if (!manifest[platform]) {
+    if (opts?.optional) return null
+    throw new CliError(`Plugin "${id}" does not support ${PLUGIN_PLATFORM_LABEL[platform]} (manifest "${platform}" is null)`)
+  }
+
+  // Namespacing: third-party channel names must be vendor-prefixed ("acme.thing").
+  if (spec.startsWith("github:")) {
+    const names = [...(manifest.provides?.views ?? []), ...(manifest.provides?.services ?? [])]
+    for (const name of names) {
+      if (!name.includes(".")) warn(`Plugin "${id}" provides bare channel name "${name}" — third-party names should be vendor-prefixed (e.g. "acme.${name}").`)
+    }
+  }
+
+  return {
+    id, dir, manifest,
+    lock: { repo, tag: checkout.tag, commit: checkout.commit, version: manifest.version ?? "unknown" },
+  }
+}
+
+/** Newest v* tag of a plugin repo, via the shared plugin cache. Null when it can't be read
+ *  (no network, no tags, local override) — `app update` reports it and moves on. */
+export const latestPluginTag = (repo: string): string | null => {
+  try { return ensureRepo(repo, null, undefined).tag } catch { return null }
+}
+
+/* ---------------------------------- desktop native plugins ---------------------------------- */
+
+/** The desktop host's plugin library target key (manifest `desktop.library` keys). */
+export const desktopPluginTarget = (): string => `${process.platform}-${process.arch}`
+
+const isDesktopPluginLibrary = (name: string): boolean => {
+  const n = name.toLowerCase()
+  return process.platform === "win32" ? n.endsWith(".dll") : n.endsWith(".so")
+}
+
+/** Native plugin libraries for THIS project on THIS machine (packages/desktop/plugin-sdk/
+ *  lecodes_plugin.h — runtime-loaded .dll/.so, no host rebuild):
+ *    - every library in the project's own `plugins/` dir — the zero-manifest dev loop (build a
+ *      DLL, drop it there, `lecodes desktop run`);
+ *    - the `desktop.library[target]` of every app.json plugin whose manifest declares one
+ *      (mobile-only plugins are skipped, not errors).
+ *  `dirs` is what a run forwards to the host as CREATOR_PLUGIN_DIRS (the host scans them);
+ *  `files` is what `app build desktop` copies into `<build>/plugins/`. `strict` turns a broken
+ *  declaration into an error (builds); runs warn and go on without that plugin. */
+export const desktopPluginLibraries = (root: string, opts: { strict?: boolean } = {}): { dirs: string[], files: string[] } => {
+  const dirs: string[] = []
+  const files: string[] = []
+  const local = join(root, "plugins")
+  if (existsSync(local) && statSync(local).isDirectory()) {
+    dirs.push(local)
+    for (const f of readdirSync(local)) if (isDesktopPluginLibrary(f)) files.push(join(local, f))
+  }
+  const config = readJson<AppConfig>(join(root, "app.json"))
+  const specs = Object.entries(config?.plugins ?? {})
+  if (specs.length === 0) return { dirs, files }
+  const lock = readJson<{ plugins?: Record<string, LockEntry> }>(join(root, "plugins.lock.json"))?.plugins ?? {}
+  const target = desktopPluginTarget()
+  for (const [id, spec] of specs) {
+    let plugin: ResolvedPlugin | null
+    try {
+      plugin = resolvePlugin(id, spec, lock[id], "desktop", { optional: true })
+    } catch (e) {
+      if (opts.strict) throw e
+      warn(`Plugin "${id}": ${(e as Error).message} — skipped for this desktop run`)
+      continue
+    }
+    const rel = plugin?.manifest.desktop?.library?.[target]
+    if (!plugin || !rel) continue   // mobile-only, or no build for this OS/arch
+    const abs = resolve(plugin.dir, rel)
+    if (!existsSync(abs)) {
+      const msg = `Plugin "${id}": desktop library ${abs} is missing (manifest desktop.library["${target}"])`
+      if (opts.strict) throw new CliError(msg)
+      warn(`${msg} — skipped for this desktop run`)
+      continue
+    }
+    files.push(abs)
+    const dir = dirname(abs)
+    if (!dirs.includes(dir)) dirs.push(dir)
+  }
+  return { dirs, files }
+}