lecodes-cli 2.4.2 → 2.4.3

package/src/compile/screenEntry.ts

@@ -1,123 +1,123 @@
-import { existsSync, readFileSync, statSync } from "node:fs"
-import { isAbsolute, join, relative, resolve } from "node:path"
-import { screenFrame } from "../project/designMeta"
-import { CliError } from "../cli"
-import { toKey } from "../project/paths"
-import type { CompileEntry } from "./projectCompile"
-
-/*
- * Rendering ONE screen module instead of the whole app — `lecodes render <file>` (and
- * `--desktop`). A design screen (`design/screens/login.ts`) never boots itself: it default-exports
- * a `UIScreen`, or a `(state) => UIScreen` function for its states, and the design board / snapshot
- * supply the `.open()`. This builds the same virtual entry for the normal project pipeline, so any
- * file written that way — inside design/ or not — renders with the full `lecodes render` flag set
- * (--png/--clip/--script/--device/…) against the project's real imports and assets.
- *
- * Kept in step with compile/designCompile.ts, which does the same wrapping per screen for the board.
- */
-
-/** Extensions a screen module may carry (so `render design/screens/login` works too). */
-const SCREEN_EXTS = [".ts", ".tsx", ".js", ".jsx", ".mjs"]
-
-/** Where the generated entry lives — the project root, so its import specifier is the screen's
- *  own project key ("./design/screens/login"). Leading dot: never a real project file. */
-const SCREEN_ENTRY_PATH = "/.screen-entry.ts"
-
-/** The design folder a bare screen id (`lecodes render login`) is looked up in. */
-const DEFAULT_DESIGN_DIR = "design"
-
-export type ScreenTarget = {
-  /** The virtual entry module — hand it to the compiler alongside the project's own entries. */
-  entry: CompileEntry
-  /** Path of that entry, for `entryOverride`. */
-  entryPath: string
-  /** The board frame from the design folder's meta.json, when this IS a design screen. */
-  frame?: [number, number]
-  /** How the screen is named in progress notes ("design/screens/login.ts", "login@empty"). */
-  label: string
-}
-
-/** `lecodes render <file|screen-id>` — the positional a screen render is asked for by. */
-
-/** Whether the argument names a path at all (vs a bare screen id). */
-const hasSeparator = (file: string) => file.includes("/") || file.includes("\\")
-
-/** Find the screen file: a path (with or without extension), or a bare id resolved against the
- *  design folder's screens/ (`lecodes render login`, honoring --dir). */
-const findScreenFile = (root: string, file: string, dirFlag: string | undefined): string => {
-  const candidates = [resolve(process.cwd(), file)]
-  if (!hasSeparator(file)) {
-    candidates.push(join(root, (dirFlag ?? DEFAULT_DESIGN_DIR).replace(/[/\\]+$/, ""), "screens", file))
-  }
-  for (const base of candidates) {
-    if (existsSync(base) && statSync(base).isFile()) return base
-    for (const ext of SCREEN_EXTS) if (existsSync(base + ext)) return base + ext
-  }
-  throw new CliError(
-    `No screen file at "${file}".` +
-    (hasSeparator(file) ? "" : ` Pass a path, or a screen id that exists in ${dirFlag ?? DEFAULT_DESIGN_DIR}/screens/.`))
-}
-
-/** The design folder a screen file belongs to ("<root>/design" for "/design/screens/login.ts"),
- *  or null when it isn't laid out as a design screen. */
-const designDirOf = (root: string, key: string): { dir: string, id: string } | null => {
-  const m = /^\/(.*)screens\/([^/]+)\.[^./]+$/.exec(key)
-  if (!m) return null
-  const dir = join(root, m[1])
-  return existsSync(join(dir, "meta.json")) ? { dir, id: m[2] } : null
-}
-
-/**
- * Resolve `<file>` into the virtual entry that opens its default export.
- * `state` picks the branch of a `(state) => UIScreen` screen (ignored by a value export).
- */
-const resolveScreenTarget = (
-  root: string, file: string, opts: { state?: string, dir?: string } = {},
-): ScreenTarget => {
-  const abs = findScreenFile(root, file, opts.dir)
-  const rel = relative(root, abs)
-  if (rel.startsWith("..") || isAbsolute(rel)) {
-    throw new CliError(
-      `"${file}" is outside the project (${root}) — a screen renders as part of its project, so its ` +
-      `imports and asset() files resolve from the same tree.`)
-  }
-  const key = toKey(rel)
-
-  // A file with no default export compiles to an empty render; say so here instead.
-  if (!/^\s*export\s+default\b/m.test(readFileSync(abs, "utf8"))) {
-    throw new CliError(
-      `${key.slice(1)} has no default export. A screen file ends with ` +
-      `\`export default UIScreen([...])\` — or \`export default (state) => UIScreen([...])\` for screen states.`)
-  }
-
-  // Same wrapper the design board compiles (designCompile.ts): a function export is invoked with the
-  // chosen state (a bare call uses the parameter's default = the canonical state), a value is used
-  // as-is, and either way the screen is opened so the runtime has something to render.
-  const invoke = opts.state !== undefined ? `screen(${JSON.stringify(opts.state)})` : "screen()"
-  const spec = "." + key.replace(/\.[^./]+$/, "")
-  const design = designDirOf(root, key)
-  return {
-    entryPath: SCREEN_ENTRY_PATH,
-    entry: {
-      path: SCREEN_ENTRY_PATH,
-      type: "text",
-      text: `import screen from ${JSON.stringify(spec)}\n`
-        + `const __screen = typeof screen === "function" ? ${invoke} : screen\n`
-        + `__screen.open()\n`,
-    },
-    frame: design ? screenFrame(design.dir, design.id) : undefined,
-    label: (design ? design.id : key.slice(1)) + (opts.state !== undefined ? `@${opts.state}` : ""),
-  }
-}
-
-/** The screen target named on the command line (`render <file>`), or undefined when no screen was
- *  named. Rejects the flag combinations that would fight over the entrypoint. */
-export type ScreenArgs = { file?: string, state?: string, entry?: string, dir?: string }
-export const screenTargetFrom = (root: string, a: ScreenArgs): ScreenTarget | undefined => {
-  if (a.file === undefined) {
-    if (a.state !== undefined) throw new CliError("--state picks a screen's state — name the screen file too: lecodes render <file> --state <name>")
-    return undefined
-  }
-  if (a.entry !== undefined) throw new CliError("Use either a screen file or --entry, not both — each names the module to compile from.")
-  return resolveScreenTarget(root, a.file, { state: a.state, dir: a.dir })
-}
+import { existsSync, readFileSync, statSync } from "node:fs"
+import { isAbsolute, join, relative, resolve } from "node:path"
+import { screenFrame } from "../project/designMeta"
+import { CliError } from "../cli"
+import { toKey } from "../project/paths"
+import type { CompileEntry } from "./projectCompile"
+
+/*
+ * Rendering ONE screen module instead of the whole app — `lecodes render <file>` (and
+ * `--desktop`). A design screen (`design/screens/login.ts`) never boots itself: it default-exports
+ * a `UIScreen`, or a `(state) => UIScreen` function for its states, and the design board / snapshot
+ * supply the `.open()`. This builds the same virtual entry for the normal project pipeline, so any
+ * file written that way — inside design/ or not — renders with the full `lecodes render` flag set
+ * (--png/--clip/--script/--device/…) against the project's real imports and assets.
+ *
+ * Kept in step with compile/designCompile.ts, which does the same wrapping per screen for the board.
+ */
+
+/** Extensions a screen module may carry (so `render design/screens/login` works too). */
+const SCREEN_EXTS = [".ts", ".tsx", ".js", ".jsx", ".mjs"]
+
+/** Where the generated entry lives — the project root, so its import specifier is the screen's
+ *  own project key ("./design/screens/login"). Leading dot: never a real project file. */
+const SCREEN_ENTRY_PATH = "/.screen-entry.ts"
+
+/** The design folder a bare screen id (`lecodes render login`) is looked up in. */
+const DEFAULT_DESIGN_DIR = "design"
+
+export type ScreenTarget = {
+  /** The virtual entry module — hand it to the compiler alongside the project's own entries. */
+  entry: CompileEntry
+  /** Path of that entry, for `entryOverride`. */
+  entryPath: string
+  /** The board frame from the design folder's meta.json, when this IS a design screen. */
+  frame?: [number, number]
+  /** How the screen is named in progress notes ("design/screens/login.ts", "login@empty"). */
+  label: string
+}
+
+/** `lecodes render <file|screen-id>` — the positional a screen render is asked for by. */
+
+/** Whether the argument names a path at all (vs a bare screen id). */
+const hasSeparator = (file: string) => file.includes("/") || file.includes("\\")
+
+/** Find the screen file: a path (with or without extension), or a bare id resolved against the
+ *  design folder's screens/ (`lecodes render login`, honoring --dir). */
+const findScreenFile = (root: string, file: string, dirFlag: string | undefined): string => {
+  const candidates = [resolve(process.cwd(), file)]
+  if (!hasSeparator(file)) {
+    candidates.push(join(root, (dirFlag ?? DEFAULT_DESIGN_DIR).replace(/[/\\]+$/, ""), "screens", file))
+  }
+  for (const base of candidates) {
+    if (existsSync(base) && statSync(base).isFile()) return base
+    for (const ext of SCREEN_EXTS) if (existsSync(base + ext)) return base + ext
+  }
+  throw new CliError(
+    `No screen file at "${file}".` +
+    (hasSeparator(file) ? "" : ` Pass a path, or a screen id that exists in ${dirFlag ?? DEFAULT_DESIGN_DIR}/screens/.`))
+}
+
+/** The design folder a screen file belongs to ("<root>/design" for "/design/screens/login.ts"),
+ *  or null when it isn't laid out as a design screen. */
+const designDirOf = (root: string, key: string): { dir: string, id: string } | null => {
+  const m = /^\/(.*)screens\/([^/]+)\.[^./]+$/.exec(key)
+  if (!m) return null
+  const dir = join(root, m[1])
+  return existsSync(join(dir, "meta.json")) ? { dir, id: m[2] } : null
+}
+
+/**
+ * Resolve `<file>` into the virtual entry that opens its default export.
+ * `state` picks the branch of a `(state) => UIScreen` screen (ignored by a value export).
+ */
+const resolveScreenTarget = (
+  root: string, file: string, opts: { state?: string, dir?: string } = {},
+): ScreenTarget => {
+  const abs = findScreenFile(root, file, opts.dir)
+  const rel = relative(root, abs)
+  if (rel.startsWith("..") || isAbsolute(rel)) {
+    throw new CliError(
+      `"${file}" is outside the project (${root}) — a screen renders as part of its project, so its ` +
+      `imports and asset() files resolve from the same tree.`)
+  }
+  const key = toKey(rel)
+
+  // A file with no default export compiles to an empty render; say so here instead.
+  if (!/^\s*export\s+default\b/m.test(readFileSync(abs, "utf8"))) {
+    throw new CliError(
+      `${key.slice(1)} has no default export. A screen file ends with ` +
+      `\`export default UIScreen([...])\` — or \`export default (state) => UIScreen([...])\` for screen states.`)
+  }
+
+  // Same wrapper the design board compiles (designCompile.ts): a function export is invoked with the
+  // chosen state (a bare call uses the parameter's default = the canonical state), a value is used
+  // as-is, and either way the screen is opened so the runtime has something to render.
+  const invoke = opts.state !== undefined ? `screen(${JSON.stringify(opts.state)})` : "screen()"
+  const spec = "." + key.replace(/\.[^./]+$/, "")
+  const design = designDirOf(root, key)
+  return {
+    entryPath: SCREEN_ENTRY_PATH,
+    entry: {
+      path: SCREEN_ENTRY_PATH,
+      type: "text",
+      text: `import screen from ${JSON.stringify(spec)}\n`
+        + `const __screen = typeof screen === "function" ? ${invoke} : screen\n`
+        + `__screen.open()\n`,
+    },
+    frame: design ? screenFrame(design.dir, design.id) : undefined,
+    label: (design ? design.id : key.slice(1)) + (opts.state !== undefined ? `@${opts.state}` : ""),
+  }
+}
+
+/** The screen target named on the command line (`render <file>`), or undefined when no screen was
+ *  named. Rejects the flag combinations that would fight over the entrypoint. */
+export type ScreenArgs = { file?: string, state?: string, entry?: string, dir?: string }
+export const screenTargetFrom = (root: string, a: ScreenArgs): ScreenTarget | undefined => {
+  if (a.file === undefined) {
+    if (a.state !== undefined) throw new CliError("--state picks a screen's state — name the screen file too: lecodes render <file> --state <name>")
+    return undefined
+  }
+  if (a.entry !== undefined) throw new CliError("Use either a screen file or --entry, not both — each names the module to compile from.")
+  return resolveScreenTarget(root, a.file, { state: a.state, dir: a.dir })
+}

package/src/plugin/emitPackage.ts

@@ -1,7 +1,8 @@
 // A plugin repo's `Package.swift`, from the manifests: the plugins with an iOS half as ONE SwiftPM
-// package — a target per plugin (its sources `plugins/<id>/ios`, the packages its manifest names)
-// and a product per plugin. Each plugin is its own MODULE, so two plugins may declare a type of the
-// same name, and an Xcode project links a plugin as a product instead of compiling its folder.
+// package — a target per plugin (its sources `plugins/<id>/ios`, the packages its manifest names,
+// a binary target per prebuilt xcframework of `ios.binaries`, by its path in the repo) and a product
+// per plugin. Each plugin is its own MODULE, so two plugins may declare a type of the same name, and
+// an Xcode project links a plugin as a product instead of compiling its folder.
 //
 // The targets depend on the LeCodes SDK as a package on disk: `LECODES_IOS_SDK_PATH`, else the path
 // the repo's package.json names (`lecodes.iosSdkPath`), else the sibling `../lecodes` (a checkout
@@ -11,7 +12,7 @@
 // of its own (templates/ios.ts), pinned by plugins.lock.json.
 
 import type { PluginManifest } from "./manifest"
-import { pascal } from "./manifest"
+import { binaryName, pascal } from "./manifest"
 
 export class PackageError extends Error {}
 
@@ -30,7 +31,8 @@ export const DEFAULT_SDK_PATH = "../lecodes"
 
 /** The text of the repo's Package.swift for `plugins` (every manifest; those without an iOS half are
  *  left out); `sdkPath` is the repo's own SDK location (package.json `lecodes.iosSdkPath`). Throws
- *  PackageError when two plugins pin one package at different versions. */
+ *  PackageError when two plugins pin one package at different versions, or when a binary's name is
+ *  another target's (one name, one target of the package). */
 export const emitPackageSwift = (plugins: { id: string, manifest: PluginManifest }[], sdkPath: string = DEFAULT_SDK_PATH): string => {
   const ios = plugins.filter(p => p.manifest.ios !== null)
   const packages = new Map<string, { url: string, exact?: string, from?: string, by: string }>()
@@ -44,6 +46,14 @@ export const emitPackageSwift = (plugins: { id: string, manifest: PluginManifest
     }
   }
   const moduleOf = (p: { id: string, manifest: PluginManifest }) => iosModule(p.id, p.manifest)
+  const targetNames = new Map<string, string>(ios.map(p => [moduleOf(p), `the module of "${p.id}"`]))
+  for (const p of ios) {
+    for (const path of p.manifest.ios!.binaries ?? []) {
+      const prior = targetNames.get(binaryName(path))
+      if (prior) throw new PackageError(`"${p.id}" carries the binary ${binaryName(path)} and ${binaryName(path)} is ${prior} — one name is one target of the package`)
+      targetNames.set(binaryName(path), `a binary of "${p.id}"`)
+    }
+  }
 
   const products = ios.map(p => `        .library(name: "${moduleOf(p)}", targets: ["${moduleOf(p)}"]),`)
   const dependencies = [
@@ -51,9 +61,11 @@ export const emitPackageSwift = (plugins: { id: string, manifest: PluginManifest
     ...[...packages.values()].map(pkg => `        .package(url: "${pkg.url}", ${pkg.exact ? `exact: "${pkg.exact}"` : `from: "${pkg.from}"`}),`),
   ]
   const targets = ios.map(p => {
+    const binaries = p.manifest.ios!.binaries ?? []
     const deps = [
       `.product(name: "LeCodes", package: "lecodes")`,
       ...(p.manifest.ios!.packages ?? []).flatMap(pkg => pkg.products.map(name => `.product(name: "${name}", package: "${swiftPackageName(pkg.url)}")`)),
+      ...binaries.map(path => `"${binaryName(path)}"`),
     ]
     return [
       `        // ${p.id}`,
@@ -62,6 +74,7 @@ export const emitPackageSwift = (plugins: { id: string, manifest: PluginManifest
       `            dependencies: [${deps.join(", ")}],`,
       `            path: "plugins/${p.id}/ios"`,
       `        ),`,
+      ...binaries.map(path => `        .binaryTarget(name: "${binaryName(path)}", path: "plugins/${p.id}/${path.split(/[\\/]/).join("/")}"),`),
     ].join("\n")
   })
 

package/src/plugin/generate.ts

@@ -95,7 +95,7 @@ export const generatePlugin = (ts: typeof tsModule, plugin: PluginDir): { contra
   }
   if (existsSync(join(plugin.dir, "android"))) {
     const name = single ? contract.channels[0]!.iface : contract.channels[0]!.iface + "Plugin"
-    const pkg = kotlinPackage(join(plugin.dir, "android"))
+    const pkg = kotlinPackage(join(plugin.dir, "android"), manifest?.android?.register)
     files.push({ file: join(pkg.dir, `${name}.gen.kt`), text: emitKotlin(lower(contract), { id, package: pkg.name }) })
   }
   if (existsSync(join(plugin.dir, "web"))) {
@@ -149,9 +149,17 @@ export const hostImports = (web: string): string[] => {
 
 /** Where a plugin's Kotlin lives: `android/` is laid out as a Gradle module (its manifest and
  *  resources travel with the sources), and the generated file is a file of the plugin's PACKAGE —
- *  the one folder under `src/main/java` that the path narrows down to. */
-export const kotlinPackage = (android: string): { dir: string, name: string } => {
+ *  the package of the type that registers the half (the manifest's `android.register`, which is
+ *  also the module's namespace), when its folder is there; else the one folder under
+ *  `src/main/java` that the path narrows down to (a plugin with no manifest yet). A half may hold
+ *  other packages beside its own (a vendored library's JNI class): they do not move the file. */
+export const kotlinPackage = (android: string, register?: string): { dir: string, name: string } => {
   const root = join(android, "src", "main", "java")
+  if (register) {
+    const name = register.split(".").slice(0, -1).join(".")
+    const dir = join(root, ...name.split("."))
+    if (name && existsSync(dir)) return { dir, name }
+  }
   let dir = root
   while (existsSync(dir)) {
     const entries = readdirSync(dir).filter(e => !e.startsWith("."))

package/src/plugin/manifest.ts

@@ -1,8 +1,8 @@
 // A plugin's manifest (`lecodes-plugin.json`, 2.x): what a host needs to BUILD the plugin in — the
 // type that registers each half, what a half asks of its platform (usage strings, entitlements,
-// packages, Gradle dependencies, bundler resources). What the plugin DOES is not here: the channels,
-// their names and their types are the contract's (contract.d.ts), the folders are the convention
-// (`sdk/`, `ios/`, `android/`, `web/`).
+// packages, prebuilt binaries, Gradle dependencies, bundler resources). What the plugin DOES is not
+// here: the channels, their names and their types are the contract's (contract.d.ts), the folders
+// are the convention (`sdk/`, `ios/`, `android/`, `web/`).
 //
 // A platform is a key of the manifest, ALWAYS: an object where the plugin has a half, `null` where
 // it has none. A missing key is refused — "not supported" is a statement, not an omission.
@@ -48,6 +48,12 @@ export type PluginManifest = {
     infoPlist?: Record<string, string>
     entitlements?: Record<string, unknown>
     packages?: IosPackage[]
+    /** Prebuilt xcframeworks the half links, by their paths in the plugin
+     *  (`binaries/ios/QrAnchorFFI.xcframework`): folders of the plugin, never under ios/ — SwiftPM
+     *  takes a binary as a target of its own, beside the sources. Each is a binary target named after
+     *  its folder (`binaryName`), which the half's target depends on; a name is one in a package
+     *  (two plugins may not carry one alike). */
+    binaries?: string[]
   } | null
   android: {
     /** The Gradle module the half is built as in a shell. Default: `lecodes-` + the id. */
@@ -91,7 +97,7 @@ const GONE: Record<string, string> = {
   desktop: "desktop plugins are another system, with a manifest of their own",
 }
 const BRANCH: Record<(typeof PLATFORMS)[number], Set<string>> = {
-  ios: new Set(["module", "register", "infoPlist", "entitlements", "packages"]),
+  ios: new Set(["module", "register", "infoPlist", "entitlements", "packages", "binaries"]),
   android: new Set(["module", "register", "dependencies", "gradlePlugins"]),
   web: new Set(["register", "dependencies", "resources", "static"]),
 }
@@ -101,6 +107,12 @@ const isFolder = (path: string): boolean => existsSync(path) && statSync(path).i
 
 export const pascal = (id: string): string => id.split("-").map(w => w.charAt(0).toUpperCase() + w.slice(1)).join("")
 
+const XCFRAMEWORK = ".xcframework"
+
+/** The binary target of an `ios.binaries` path: its folder's name without `.xcframework`
+ *  (`binaries/ios/QrAnchorFFI.xcframework` → `QrAnchorFFI`). */
+export const binaryName = (path: string): string => path.split(/[\\/]/).pop()!.slice(0, -XCFRAMEWORK.length)
+
 /** The manifest of the plugin in `dir` (its folder's name is its id). Every problem of the file is
  *  reported at once. */
 export const readManifest = (dir: string, id: string): PluginManifest => {
@@ -181,6 +193,23 @@ export const readManifest = (dir: string, id: string): PluginManifest => {
         }
       })
     }
+    if (ios.binaries !== undefined) {
+      if (!Array.isArray(ios.binaries)) problems.push(`ios.binaries: a list of the plugin's xcframeworks, by their paths in it ("binaries/ios/X.xcframework")`)
+      else {
+        const named = new Map<string, string>()
+        ios.binaries.forEach((path, i) => {
+          const segments = typeof path === "string" ? path.split(/[\\/]/) : []
+          if (typeof path !== "string" || path.trim() === "" || isAbsolute(path) || segments.some(s => s === ".." || s === "." || s === "")) {
+            problems.push(`ios.binaries[${i}]: a folder of the plugin, by its path in it ("binaries/ios/X.xcframework")`)
+          } else if (!path.endsWith(XCFRAMEWORK)) problems.push(`ios.binaries[${i}]: "${path}" — an ${XCFRAMEWORK} folder`)
+          else if (segments[0] === "ios") problems.push(`ios.binaries[${i}]: ${path} is in ios/, the half's sources — a binary stands beside them ("binaries/ios/X.xcframework")`)
+          else if (!/^[A-Za-z_]\w*$/.test(binaryName(path))) problems.push(`ios.binaries[${i}]: "${path}" — the folder's name is its binary target's: a Swift name before ${XCFRAMEWORK}`)
+          else if (!isFolder(join(dir, path))) problems.push(`ios.binaries[${i}]: ${path} is not a folder of the plugin`)
+          else if (named.has(binaryName(path))) problems.push(`ios.binaries[${i}]: ${path} is named "${binaryName(path)}" like ${named.get(binaryName(path))} — a name is one binary target`)
+          else named.set(binaryName(path), path)
+        })
+      }
+    }
   }
   const android = isObject(raw.android) ? raw.android : null
   if (android) {