lecodes-cli 2.0.6 → 2.0.8

package/src/commands/app/index.ts

@@ -14,7 +14,7 @@ import {
 } from "./templates/ios"
 import {
   FIRST_PARTY_PLUGINS, SDK_VARIANTS, cmpVersion, ensureShellIgnored,
-  fetchLatestSdkVersion, latestPluginTag, projectRoot, readJson, resolvePlugin, resolveSdkVersion,
+  fetchLatestSdkVersion, isLocalPluginSpec, latestPluginTag, projectRoot, readJson, resolvePlugin, resolveSdkVersion, sdkSatisfies,
   resolveVariant, runTool, slugify, writeJson, VERSION_RE, type AppConfig, type LockEntry,
 } from "./shared"
 import {
@@ -61,16 +61,18 @@ import { loadIconMaster, writeIosAppIcon } from "./icon"
 
 const SDK_REPO = "letary/lecodes-ios-sdk"
 
-// Oldest lecodes-ios-sdk a generated shell can use — 1.2.0 = variant matrix (core/2d/3d/full)
-// + LeCodesUpdater (native OTA), both of which the generated files assume. The version a shell
-// actually links is app.json `ios.sdk` (init pins the newest release, `app update` moves it);
-// this floor is only the last-resort fallback when the network is unavailable at init.
-const SDK_MIN_VERSION = "1.2.0"
+// Oldest lecodes-ios-sdk a generated shell can use — 2.0.7 = the first 2.x release: a SOURCE
+// package over the engine, one tag per variant (`<version>` = full, `-3d`, `-2d`, `-core`),
+// LeCodesShellViewController + LeCodesUpdater, which the generated files assume. The version a
+// shell actually links is app.json `ios.sdk` (init pins the newest release, `app update` moves
+// it); this floor is only the last-resort fallback when the network is unavailable at init. A 1.x
+// shell is moved here by `lecodes app update` (its CLI-owned files are regenerated; its
+// App/ViewController.swift keeps compiling: LeCodesViewController and LeCodesUpdater exist in 2.x).
+const SDK_MIN_VERSION = "2.0.7"
 
 // First lecodes-ios-sdk release with `LeCodesEngine.bootProjectUuid` — the shell's world
-// identity (docs/push-plan.md). On older SDKs sync simply doesn't bake the uuid (and warns
-// when push is installed) instead of generating code the linked release can't compile.
-const SDK_IDENTITY_VERSION = "1.6.0"
+// identity (docs/push-plan.md); every 2.x release has it.
+const SDK_IDENTITY_VERSION = "2.0.7"
 
 /** The SDK version a synced shell currently links (Package.swift is CLI-owned, so its
  *  `exact:` pin is the truth) — the offline fallback, so a sync without network never
@@ -78,8 +80,8 @@ const SDK_IDENTITY_VERSION = "1.6.0"
 const shellSdkVersion = (iosDir: string): string | null => {
   const path = join(iosDir, "LeCodesRuntime", "Package.swift")
   if (!existsSync(path)) return null
-  const m = /lecodes-ios-sdk\.git",\s*(?:exact|from):\s*"([^"]+)"/.exec(readFileSync(path, "utf8"))
-  return m && VERSION_RE.test(m[1]) ? m[1] : null
+  const m = /lecodes-ios-sdk\.git",\s*(?:exact|from):\s*"(\d+\.\d+\.\d+)(?:-(?:core|2d|3d))?"/.exec(readFileSync(path, "utf8"))
+  return m && VERSION_RE.test(m[1]) ? m[1] : null   // a LECODES_IOS_SDK_PATH shell names no release: null
 }
 
 const IOS_SDK_OPTS = { repo: SDK_REPO, minVersion: SDK_MIN_VERSION, configKey: "ios.sdk" }
@@ -173,7 +175,7 @@ const initIos = async (opts: IosInitOptions): Promise<void> => {
   // "auto" resolves at sync time (the compiled bundle says which engines it uses); until the
   // first sync the shell gets the slimmest product as a placeholder.
   write("LeCodesRuntime/Package.swift", runtimePackageTemplate(sdkVersion, variant === "auto" ? "core" : variant as SdkVariant, []))
-  write("LeCodesRuntime/Sources/LeCodesRuntime/LeCodesRuntime.swift", runtimeSwiftTemplate([]))
+  write("LeCodesRuntime/Sources/LeCodesRuntime/LeCodesRuntime.swift", runtimeSwiftTemplate([], undefined, variant === "auto" ? "core" : variant as SdkVariant))
 
   log("")
   log(`${c.green("sdk")}       lecodes-ios-sdk ${sdkVersion}${sdk === "latest" ? c.dim("  (ios.sdk: latest — re-resolved on every sync)") : c.dim("  (pinned in app.json ios.sdk — `lecodes app update` moves it)")}`)
@@ -210,46 +212,22 @@ const init = defineCommand({
 
 /* --------------------------------------- sync --------------------------------------- */
 
-/** The filament resources bundle that must ship beside any CreatorGL-bearing variant (3d/full).
- *  Published as a release asset next to the SDK binaries; downloaded once per SDK version into
- *  ~/.lecodes/sdk-resources/. `LECODES_SDK_RESOURCES` overrides with a local .bundle — the
- *  SDK-development loop, like LECODES_PLUGINS_DIR for plugins. */
-const ensureSdkResourcesBundle = async (sdkVersion: string): Promise<string> => {
-  const override = process.env.LECODES_SDK_RESOURCES
-  if (override) {
-    note(`Using local resources bundle ${override} (LECODES_SDK_RESOURCES)`)
-    return resolve(override)
-  }
-  const dir = join(homedir(), ".lecodes", "sdk-resources", sdkVersion)
-  const bundle = join(dir, "LeCodesSDKResources.bundle")
-  if (existsSync(bundle)) return bundle
-  const url = `https://github.com/${SDK_REPO}/releases/download/${sdkVersion}/LeCodesSDKResources.bundle.zip`
-  note(`Downloading LeCodesSDKResources.bundle (SDK ${sdkVersion})…`)
-  const res = await fetch(url)
-  if (!res.ok) throw new CliError(`Resources bundle download failed (HTTP ${res.status}) — ${url}`)
-  mkdirSync(dir, { recursive: true })
-  const zip = join(dir, "LeCodesSDKResources.bundle.zip")
-  writeFileSync(zip, new Uint8Array(await res.arrayBuffer()))
-  execFileSync("ditto", ["-x", "-k", zip, dir])   // release zips are ditto archives (--keepParent)
-  rmSync(zip)
-  if (!existsSync(bundle)) throw new CliError(`No LeCodesSDKResources.bundle inside the release asset ${url}`)
-  return bundle
-}
-
-/** Resolve app.json "update" to the URL the shell's native updater checks. `true` means the
- *  project's live bundle on the platform (`/code/<uuid>.js` — needs a server-backed project);
- *  strings / { url } pass through. Warns on http: ATS blocks it on device. */
-const resolveUpdateUrl = (update: AppConfig["update"], root: string): string | undefined => {
-  if (!update) return undefined
+/** Resolve app.json "update" to the URL the shell's native updater checks (LeCodesUpdater):
+ *  absent or `true` = the project's live bundle on the platform — `/code/<uuid>.js?sdk=<version>`,
+ *  the launcher's own URL, so a pushed project updates its shells with no server of its own (a
+ *  local-only project has none: unconfigured); `false` = no OTA; a string / { url } = custom
+ *  hosting, passed through. Warns on http: ATS blocks it on device. */
+const resolveUpdateUrl = (update: AppConfig["update"], root: string, sdkVersion: string): string | undefined => {
+  if (update === false) return undefined
   let url = typeof update === "string" ? update : typeof update === "object" ? update.url : undefined
   if (!url) {
     let manifest: Manifest | null = null
     try { manifest = readManifest(root) } catch { /* not a project dir */ }
     if (!manifest) {
-      warn(`app.json "update": true needs a server-backed project — use "update": {"url": "https://…/app.js"} for custom hosting. OTA left unconfigured.`)
+      if (update) warn(`app.json "update": true needs a server-backed project — use "update": {"url": "https://…/app.js"} for custom hosting. OTA left unconfigured.`)
       return undefined
     }
-    url = `${requireApiUrl(loadConfig())}/code/${manifest.uuid}.js`
+    url = `${requireApiUrl(loadConfig())}/code/${manifest.uuid}.js?sdk=${sdkVersion}`
   }
   if (!url.startsWith("https://")) warn(`update URL is not https — iOS blocks it on device (ATS): ${url}`)
   return url
@@ -307,16 +285,17 @@ const syncIos = async (root: string, config: AppConfig): Promise<SyncArtifacts>
     const register = ios.register
     if (!module || !register) throw new CliError(`Plugin "${id}": manifest ios.module / ios.register missing`)
 
-    const src = join(plugin.dir, ios.sources ?? "ios")
-    if (!existsSync(src)) throw new CliError(`Plugin "${id}": sources dir ${src} missing`)
+    const src = join(plugin.dir, "ios")
+    if (!existsSync(src)) throw new CliError(`Plugin "${id}": ios/ folder missing in ${plugin.dir}`)
     const dest = join(sourcesDir, module)
     rmSync(dest, { recursive: true, force: true })
     cpSync(src, dest, { recursive: true })
 
-    // Hard error, not a warning: below minSdk the vendored sources reference SDK API that
-    // does not exist in the linked release, so the shell cannot compile anyway.
-    if (ios.minSdk && VERSION_RE.test(ios.minSdk) && cmpVersion(sdkVersion, ios.minSdk) < 0) {
-      throw new CliError(`Plugin "${id}" needs lecodes-ios-sdk ${ios.minSdk} but the shell links ${sdkVersion} — run \`lecodes app update\` (or set app.json ios.sdk).`)
+    // Hard error, not a warning: outside the plugin's `sdk` range the vendored sources reference
+    // an SDK API the linked release does not have (or another contract major), so the shell
+    // cannot compile anyway.
+    if (!sdkSatisfies(sdkVersion, plugin.manifest.sdk)) {
+      throw new CliError(`Plugin "${id}" is written for lecodes-ios-sdk ${plugin.manifest.sdk} but the shell links ${sdkVersion} — run \`lecodes app update\` (or set app.json ios.sdk).`)
     }
     for (const [key, value] of Object.entries(ios.infoPlist ?? {})) {
       (infoValues[key] ??= []).push(value)
@@ -363,21 +342,11 @@ const syncIos = async (root: string, config: AppConfig): Promise<SyncArtifacts>
   const sdkWhy = sdkPin === "latest" ? "latest" : config.ios.sdk ? "pinned by ios.sdk" : "from the shell — set ios.sdk or run `lecodes app update`"
   log(`${c.green("sdk")}       lecodes-ios-sdk ${sdkVersion}${c.dim(`  (${sdkWhy})`)}`)
 
-  // The filament resources ride along with any CreatorGL-bearing variant. Its files also back
-  // fetchLocal for SDK built-ins (lit.filamat & co), so the embed step below can skip them.
-  const sdkProvided = new Set<string>()
-  if (variant === "3d" || variant === "full") {
-    const sdkResources = await ensureSdkResourcesBundle(sdkVersion)
-    cpSync(sdkResources, join(resourcesDir, "LeCodesSDKResources.bundle"), { recursive: true })
-    for (const f of readdirSync(sdkResources)) if (f !== "Info.plist") sdkProvided.add(f)
-    log(`${c.green("resources")} LeCodesSDKResources.bundle (filament) → ios/App/Resources/`)
-  }
-
   // Embed exactly what the bundle resolves locally: the `// preload:` header names every
   // fetchLocal resource (vendored fonts included). resources.remote entries stayed URLs, and
   // an asset the code never references isn't shipped. Copies are flat by lookup name — the
-  // host's setFetchLocal reads Resources/ by basename, falling back to the SDK resources
-  // bundle for the sdkProvided names.
+  // engine's fetchLocal reads the app bundle by file name; the SDK's own blobs (the shader
+  // archives, the IBL) ride inside the SDK package and are never named here.
   const preload = /^\/\/ preload: (.*)$/m.exec(bundleJs)?.[1].split(";").map((s) => s.trim()).filter(Boolean) ?? []
   // engine-synthesized, not project files: the ubershader archive, the capture flag and the
   // engine's own materials (`material:<name>` — they ride the SDK)
@@ -394,7 +363,7 @@ const syncIos = async (root: string, config: AppConfig): Promise<SyncArtifacts>
     if (IMPLICIT_PRELOADS.has(name)) continue
     const candidates = byName.get(name) ?? []
     if (candidates.length === 0) {
-      if (!sdkProvided.has(name)) warn(`bundle needs local asset "${name}" but no project file provides it — it won't load on device`)
+      warn(`bundle needs local asset "${name}" but no project file provides it — it won't load on device`)
       continue
     }
     if (candidates.length > 1) warn(`asset name collision: ${name} (${candidates.map((r) => r.path).join(", ")}) — embedding ${candidates[0].path}`)
@@ -421,21 +390,18 @@ const syncIos = async (root: string, config: AppConfig): Promise<SyncArtifacts>
 
   // ---- regenerate the CLI-owned files ----
   writeFileSync(join(iosDir, "README.md"), IOS_README)
-  writeFileSync(join(iosDir, "LeCodesRuntime", "Package.swift"), runtimePackageTemplate(sdkVersion, variant, runtimePlugins))
-  writeFileSync(join(sourcesDir, "LeCodesRuntime", "LeCodesRuntime.swift"), runtimeSwiftTemplate(runtimePlugins, shellUuid))
+  const sdkPath = process.env.LECODES_IOS_SDK_PATH
+  if (sdkPath) note(`Using local SDK package ${sdkPath} (LECODES_IOS_SDK_PATH) — the shell links it by path, not the ${sdkVersion} release`)
+  writeFileSync(join(iosDir, "LeCodesRuntime", "Package.swift"), runtimePackageTemplate(sdkVersion, variant, runtimePlugins, sdkPath ? resolve(sdkPath) : undefined))
+  writeFileSync(join(sourcesDir, "LeCodesRuntime", "LeCodesRuntime.swift"), runtimeSwiftTemplate(runtimePlugins, shellUuid, variant))
 
   const mergedKeys: Record<string, string> = {}
   for (const [key, values] of Object.entries(infoValues)) mergedKeys[key] = [...new Set(values)].join(" ")
-  const updateUrl = resolveUpdateUrl(config.update, root)
+  const updateUrl = resolveUpdateUrl(config.update, root, sdkVersion)
   writeFileSync(join(iosDir, "App", "Info.plist"), infoPlistTemplate(mergedKeys, updateUrl))
-  if (updateUrl) log(`${c.green("update")}    OTA source ${updateUrl} — checked natively at launch, new code applies next launch`)
-  else if (!config.update) {
-    // Discoverability: server-backed projects get OTA with one app.json key, but nothing
-    // else ever mentions it. One dim line, only while unconfigured.
-    let manifest: Manifest | null = null
-    try { manifest = readManifest(root) } catch { /* not a project dir */ }
-    if (manifest) note(`tip: add "update": true to app.json for over-the-air JS updates — ship with \`lecodes push --publish\`, no store release`)
-  }
+  if (updateUrl) log(`${c.green("update")}    OTA source ${updateUrl} — checked natively at launch, new code applies next launch${config.update === undefined ? c.dim('  ("update": false in app.json turns it off)') : ""}`)
+  else if (config.update === false) log(`${c.green("update")}    off (app.json "update": false)`)
+  else note(`no OTA: a local-only project has no bundle on the platform — push it, or set "update": {"url": "https://…/app.js"} for custom hosting`)
 
   if (pluginSpecs.length > 0 || existsSync(lockPath)) writeJson(lockPath, { plugins: newLock })
 
@@ -495,7 +461,7 @@ const sync = defineCommand({
   name: "sync",
   summary: "Make every existing shell match the project: bundle + assets + SDK variant + plugins + CLI-owned files",
   usage: "[ios|android]",
-  description: "Compiles the bundle and embeds the assets it references (ios/App/Resources/ resp. the android assets/; offline by default, also for server projects — app.json \"resources\": {\"remote\": [globs]} keeps heavy assets streaming), picks the SDK variant from the bundle's engine use, vendors the app.json plugins (pinned in plugins.lock.json) and regenerates the CLI-owned shell files. User files (ios/App/*.swift, android/app/) are never touched.\n\napp.json \"update\": true (or {\"url\": …}) enables native OTA JS updates at launch (iOS). app.json \"icon\" (a square ≥1024px image) renders the app icons every sync (\"iconBackground\": the adaptive / flatten backdrop). No platform = every shell that exists; a dual-shell project compiles once.",
+  description: "Compiles the bundle and embeds the assets it references (ios/App/Resources/ resp. the android assets/; offline by default, also for server projects — app.json \"resources\": {\"remote\": [globs]} keeps heavy assets streaming), picks the SDK variant from the bundle's engine use, vendors the app.json plugins (pinned in plugins.lock.json) and regenerates the CLI-owned shell files. User files (ios/App/*.swift, android/app/) are never touched.\n\nNative OTA JS updates at launch (iOS): on by default for a pushed project (its bundle on the platform, the launcher's own URL), app.json \"update\": {\"url\": …} for custom hosting, \"update\": false turns it off. app.json \"icon\" (a square ≥1024px image) renders the app icons every sync (\"iconBackground\": the adaptive / flatten backdrop). No platform = every shell that exists; a dual-shell project compiles once.",
   examples: ["lecodes app sync", "lecodes app sync android"],
   run: ({ args }) => runSync(args[0]),
 })
@@ -523,9 +489,13 @@ const pluginList = (): void => {
 }
 
 const pluginAdd = (id: string | undefined): void => {
-  if (!id) throw new UsageError("Which plugin? `lecodes app plugin add <id | github:owner/repo[@tag]>`")
+  if (!id) throw new UsageError("Which plugin? `lecodes app plugin add <id | github:owner/repo[@tag] | ./plugins/<id>>`")
   const { configPath, config } = pluginConfig()
-  if (id.startsWith("github:")) {
+  if (isLocalPluginSpec(id)) {
+    const bare = basename(id.replace(/\/+$/, ""))
+    config.plugins[bare] = id
+    log(`${c.green("added")}     ${bare} → ${id}  ${c.dim("(a plugin of this project: its folder, as it is)")}`)
+  } else if (id.startsWith("github:")) {
     const bare = id.slice("github:".length).split("@")[0].split("/").pop()!
     config.plugins[bare] = id
     log(`${c.green("added")}     ${bare} → ${id}  ${c.dim("(third-party native code — review it before shipping)")}`)
@@ -552,14 +522,14 @@ const pluginRemove = (id: string | undefined): void => {
 const plugin = defineCommand({
   name: "plugin",
   summary: "Manage native plugins in app.json: list | add | remove (then run `lecodes app sync`)",
-  description: `Bare \`lecodes app plugin\` lists them with their plugins.lock.json pins. \`add\` takes a first-party id (${Object.keys(FIRST_PARTY_PLUGINS).join(", ")}) or github:owner/repo[@tag] for a third-party plugin (native code — review it before shipping). Nothing reaches the shell until the next sync.`,
+  description: `Bare \`lecodes app plugin\` lists them with their plugins.lock.json pins. \`add\` takes a first-party id (${Object.keys(FIRST_PARTY_PLUGINS).join(", ")}), github:owner/repo[@tag] for a third-party plugin (native code — review it before shipping), or the folder of a plugin of this project (./plugins/<id> — written with \`lecodes plugin gen\`, nothing to publish). Nothing reaches the shell until the next sync.`,
   commands: [
     defineCommand({ name: "list", summary: "The plugins in app.json and their lock pins", run: () => pluginList() }),
     defineCommand({
       name: "add",
       summary: "Add a plugin: a known id, or github:owner/repo[@tag]",
       usage: "<id | github:owner/repo[@tag]>",
-      examples: ["lecodes app plugin add camera", "lecodes app plugin add github:acme/lecodes-plugin-thing@v1.2.0"],
+      examples: ["lecodes app plugin add camera", "lecodes app plugin add github:acme/lecodes-plugin-thing@v1.2.0", "lecodes app plugin add ./plugins/acme-dial"],
       run: ({ args }) => pluginAdd(args[0]),
     }),
     defineCommand({ name: "remove", summary: "Remove a plugin entry", usage: "<id>", run: ({ args }) => pluginRemove(args[0]) }),
@@ -651,6 +621,11 @@ export const runAppUpdate = async (opts: AppUpdateOptions = {}): Promise<void> =
     const kept: Record<string, LockEntry> = {}
     for (const [id, spec] of specs) {
       const entry = lock[id]
+      if (isLocalPluginSpec(spec)) {
+        log(`${c.green("plugin")}    ${id} ${c.dim(`a folder of the project (${spec}) — synced as it is`)}`)
+        if (entry) kept[id] = entry
+        continue
+      }
       if (spec.startsWith("github:") && spec.includes("@")) {
         log(`${c.green("plugin")}    ${id} ${c.dim(`pinned by app.json (${spec}) — not updated`)}`)
         if (entry) kept[id] = entry
@@ -727,10 +702,9 @@ const doctorIosChecks = async (root: string, config: AppConfig, check: Check) =>
   if (existsSync(bundle) && validVariant) {
     const { variant } = resolveVariant(requestedVariant, readFileSync(bundle, "utf8"))
     const pkg = readFileSync(join(root, "ios", "LeCodesRuntime", "Package.swift"), "utf8")
-    const needsResources = variant === "3d" || variant === "full"
-    const hasResources = existsSync(join(root, "ios", "App", "Resources", "LeCodesSDKResources.bundle"))
-    check(pkg.includes(`"LeCodesSDK-${variant}"`) && (!needsResources || hasResources),
-      `SDK variant ${variant}${needsResources ? " (+ filament resources)" : ""}`, "run `lecodes app sync`")
+    const tag = /lecodes-ios-sdk\.git",\s*exact:\s*"([^"]+)"/.exec(pkg)?.[1] ?? ""
+    const tagVariant = (/-(core|2d|3d)$/.exec(tag)?.[1] ?? "full") as SdkVariant
+    check(tagVariant === variant, `SDK variant ${variant}`, "run `lecodes app sync`")
   }
 
   // SDK: the shell must link the version app.json asks for, and (soft, needs network) that

package/src/commands/app/shared.ts

@@ -5,6 +5,13 @@ import { dirname, join, resolve } from "node:path"
 import { findProjectRoot } from "../../project/manifest"
 import { DEFAULT_IGNORE_FILE } from "../../project/ignore"
 import { CliError, c, log, note, warn } from "../../cli"
+import { pascal, readManifest as readPluginManifest, type IosPackage, type PluginManifest as PluginManifest2 } from "../../plugin/manifest"
+
+/** The 2.x manifest (plugin/manifest.ts), plus the desktop branch the desktop flow reads: a
+ *  PREBUILT shared library per OS/arch behind the C ABI in hosts/desktop/plugin-sdk — another
+ *  system, with a manifest of its own (the 2.x reader refuses the key; desktop plugins are
+ *  resolved from the project's plugins/ folder). */
+export type PluginManifest = PluginManifest2 & { desktop?: { library?: Record<string, string> } | null }
 
 /* Shared plumbing for the `lecodes app` platform arms (index.ts = iOS + the command tree,
  * android.ts = Android, desktop.ts = the portable desktop build) and for every other command that
@@ -12,7 +19,9 @@ import { CliError, c, log, note, warn } from "../../cli"
  * 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). */
+ *  use a `github:owner/repo[@tag]` spec in app.json instead (manifest at the repo root); a plugin
+ *  of the project itself a PATH (`./plugins/<id>` — the folder with its lecodes-plugin.json,
+ *  generated by `lecodes plugin gen`; nothing to publish). */
 export const FIRST_PARTY_PLUGINS: Record<string, string> = {
   "camera": "letary/lecodes-plugins",
   "qr-scanner": "letary/lecodes-plugins",
@@ -227,74 +236,32 @@ export const desktopDefaultViewport = (root: string): { width: number, height: n
   }
 }
 
-/** 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 (hosts/desktop): a PREBUILT shared library per OS/arch behind the C ABI in
-   *  `hosts/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 type { IosPackage }
 
 export interface LockEntry { repo: string, tag: string, commit: string, version: string }
 
+/** A plugin spec that names a folder of the project (`./plugins/x`, `../x`, `/abs`, `file:x`). */
+export const isLocalPluginSpec = (spec: string): boolean =>
+  spec.startsWith("./") || spec.startsWith("../") || spec.startsWith("/") || spec.startsWith("file:")
+
+/** Does the SDK `version` a shell links satisfy a plugin manifest's `sdk` range (`^2.0.0`: the
+ *  same major, not older; `~2.1.0`: the same major.minor, not older; `2.0.0`: exactly)? */
+export const sdkSatisfies = (version: string, range: string): boolean => {
+  const op = range.startsWith("^") ? "^" : range.startsWith("~") ? "~" : ""
+  const want = range.slice(op.length)
+  if (!VERSION_RE.test(version) || !VERSION_RE.test(want)) return false
+  const [vMaj, vMin] = version.split(".").map(Number)
+  const [wMaj, wMin] = want.split(".").map(Number)
+  if (op === "") return version === want
+  if (vMaj !== wMaj) return false
+  if (op === "~" && vMin !== wMin) return false
+  return cmpVersion(version, want) >= 0
+}
+
 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.
@@ -484,6 +451,19 @@ const PLUGIN_PLATFORM_LABEL: Record<PluginPlatform, string> = { ios: "iOS", andr
 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 {
+  // A plugin of the project itself: its folder, as it is — no clone, no tag, nothing to publish.
+  if (isLocalPluginSpec(spec)) {
+    const dir = resolve(projectRoot(), spec.startsWith("file:") ? spec.slice("file:".length) : spec)
+    if (!existsSync(dir)) throw new CliError(`Plugin "${id}": ${spec} is not a folder (${dir})`)
+    const manifest: PluginManifest = readPluginManifest(dir, id)
+    fillManifestDefaults(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)`)
+    }
+    return { id, dir, manifest, lock: { repo: "local", tag: "local", commit: "local", version: manifest.version } }
+  }
+
   let repo: string
   let subdir: string
   let wantTag: string | null = null
@@ -503,28 +483,27 @@ export function resolvePlugin(id: string, spec: string, lock: LockEntry | undefi
 
   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 (!existsSync(join(dir, "lecodes-plugin.json"))) throw new CliError(`Plugin "${id}": no lecodes-plugin.json in ${dir}`)
+  const manifest: PluginManifest = readPluginManifest(dir, id)   // the 2.x manifest: every problem of it at once
+  fillManifestDefaults(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" },
+    lock: { repo, tag: checkout.tag, commit: checkout.commit, version: manifest.version },
   }
 }
 
+/** The manifest's defaults (plugin/manifest.ts documents them): the iOS module `LeCodes<Id>`,
+ *  the Android module `lecodes-<id>`. */
+const fillManifestDefaults = (manifest: PluginManifest, id: string): void => {
+  if (manifest.ios) manifest.ios.module ??= "LeCodes" + pascal(id)
+  if (manifest.android) manifest.android.module ??= "lecodes-" + id
+}
+
 /** 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 => {