lecodes-cli 0.20.0 → 0.20.2

package/src/peerInstall.ts

@@ -0,0 +1,160 @@
+import { spawnSync } from "node:child_process"
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs"
+import { join } from "node:path"
+import { pathToFileURL } from "node:url"
+import pkg from "../package.json"
+import { peerDirInPrefix, peersDir, peerVersionGlobal } from "./peers"
+import { CliError, c, confirm, log, note } from "./util"
+
+/*
+ * Peers install themselves on first use. `lecodes render` on a machine with only the CLI asks once,
+ * then puts lecodes-renderer (+ @napi-rs/canvas for PNG) into ~/.lecodes/peers and loads it from
+ * there — the same pattern as matc and the desktop host (downloaded into ~/.lecodes on first use),
+ * applied to npm packages. Why a private prefix and not `npm install -g`: no sudo / system prefix
+ * to guess, and the runtime-set peer is installed at EXACTLY this CLI's version — the compiler and the
+ * headless host are one ABI set, so a global renderer that drifted behind the CLI is the very failure
+ * this removes. A newer CLI re-installs its own version on the next use (peerSpec → `lecodes update`).
+ *
+ * Consent: an interactive terminal is asked (default yes); `--yes` / `-y` on any command or
+ * LECODES_YES=1 (CI) skips the question; a non-interactive run without either fails with the exact
+ * command to run by hand. Installer: npm if on PATH, else bun; neither → a clear error (the standalone
+ * binary on a machine without Node can't install packages — it says so).
+ *
+ * Search order when a command needs a peer: the bare specifier (global / the workspace — what the
+ * user installed by hand always wins) → the prefix → install into the prefix, then load from there.
+ */
+
+const CANVAS_RANGE_FALLBACK = "^0.1.65"
+
+const readJson = (path: string): any => { try { return JSON.parse(readFileSync(path, "utf8")) } catch { return null } }
+
+/** The npm spec a peer installs at: the renderer at exactly this CLI's version (one ABI set), canvas
+ *  at the range the installed renderer declares, the editors / assets at this CLI's peer ranges. */
+export const peerSpec = (name: string): string => {
+  if (name === "lecodes-renderer") return `lecodes-renderer@${pkg.version}`
+  if (name === "@napi-rs/canvas") {
+    const renderer = readJson(join(peerDirInPrefix("lecodes-renderer"), "package.json"))
+    const range = renderer?.peerDependencies?.["@napi-rs/canvas"] ?? renderer?.optionalDependencies?.["@napi-rs/canvas"] ?? CANVAS_RANGE_FALLBACK
+    return `@napi-rs/canvas@${range}`
+  }
+  const range = (pkg.peerDependencies as Record<string, string> | undefined)?.[name]
+  return range ? `${name}@${range}` : `${name}@latest`
+}
+
+/** Peers that only make sense together: the renderer's PNG output needs canvas next to it. */
+const companions = (name: string): string[] => name === "lecodes-renderer" ? ["lecodes-renderer", "@napi-rs/canvas"] : [name]
+
+const onPath = (cmd: string): boolean => {
+  try { return spawnSync(cmd, ["--version"], { stdio: "ignore", shell: process.platform === "win32" }).status === 0 } catch { return false }
+}
+const pickInstaller = (): "npm" | "bun" | null => onPath("npm") ? "npm" : onPath("bun") ? "bun" : null
+
+const manualCommand = (dir: string, specs: string[]) => `npm install --prefix "${dir}" ${specs.join(" ")}`
+
+/**
+ * Install peers into the prefix. Asks for consent unless `opts.yes` / LECODES_YES / `--yes` say so;
+ * throws CliError with the manual command when it can't ask or the user declines.
+ */
+export const installPeers = async (names: string[], why: string, opts: { yes?: boolean } = {}): Promise<void> => {
+  const dir = peersDir()
+  mkdirSync(dir, { recursive: true })
+  const manifest = join(dir, "package.json")
+  if (!existsSync(manifest)) {
+    writeFileSync(manifest, JSON.stringify({
+      name: "lecodes-peers", private: true,
+      description: "Optional lecodes-cli peers, installed on first use. Safe to delete — the CLI re-installs what a command needs.",
+    }, null, 2) + "\n")
+  }
+  // The renderer must be in place before canvas's range can be read off it — install in order.
+  const ordered = [...names].sort((a, b) => (a === "lecodes-renderer" ? -1 : b === "lecodes-renderer" ? 1 : 0))
+  const specsNow = ordered.map(peerSpec)
+
+  const yes = opts.yes === true || !!process.env.LECODES_YES
+  if (!yes) {
+    const interactive = process.stdin.isTTY && process.stdout.isTTY
+    if (!interactive) {
+      throw new CliError(`${why} needs ${names.join(" + ")}, which isn't installed. Re-run with --yes to install it into ${dir}, or install by hand:  ${manualCommand(dir, specsNow)}`)
+    }
+    log(`${why} needs ${c.bold(names.join(" + "))}.`)
+    log(c.dim(`It installs once into ${dir} (no admin rights); a newer CLI re-installs its own version.`))
+    if (!(await confirm("Install now?", true))) {
+      throw new CliError(`Not installed. When you want it:  ${manualCommand(dir, specsNow)}`)
+    }
+  }
+
+  const tool = pickInstaller()
+  if (!tool) throw new CliError(`Neither npm nor bun is on PATH, so ${names.join(" + ")} can't be installed automatically. Install one, or run on a machine with Node:  ${manualCommand(dir, specsNow)}`)
+
+  for (const name of ordered) {
+    const spec = peerSpec(name) // canvas's range comes from the renderer installed a step earlier
+    const argv = tool === "npm"
+      ? ["install", "--prefix", dir, "--no-audit", "--no-fund", "--loglevel=error", spec]
+      : ["add", "--cwd", dir, spec]
+    note(`$ ${tool} ${argv.join(" ")}`)
+    const r = spawnSync(tool, argv, { stdio: "inherit", shell: process.platform === "win32", timeout: 10 * 60_000 })
+    if (r.error) throw new CliError(`${tool} could not run: ${r.error.message}`)
+    if (r.status !== 0) throw new CliError(`${tool} exited with ${r.status ?? "a signal"} while installing ${spec}. By hand:  ${manualCommand(dir, [spec])}`)
+    if (!existsSync(join(peerDirInPrefix(name), "package.json"))) throw new CliError(`${name} did not land in ${dir} — the installer finished but the package is missing`)
+  }
+}
+
+/** The file a package subpath points at, read from its exports map (string, or a conditions object —
+ *  `import` / `node` / `default`), falling back to `main`. Absolute path. */
+const resolveEntry = (pkgDir: string, subpath?: string): string => {
+  const manifest = readJson(join(pkgDir, "package.json"))
+  if (!manifest) throw new CliError(`${pkgDir} holds no package.json`)
+  const key = subpath ? `./${subpath}` : "."
+  const pick = (target: unknown): string | null => {
+    if (typeof target === "string") return target
+    if (target && typeof target === "object") {
+      const t = target as Record<string, unknown>
+      for (const cond of ["import", "node", "default", "require"]) if (cond in t) { const p = pick(t[cond]); if (p) return p }
+    }
+    return null
+  }
+  let rel: string | null = null
+  const exp = manifest.exports
+  if (typeof exp === "string") rel = key === "." ? exp : null
+  else if (exp && typeof exp === "object") rel = pick((exp as Record<string, unknown>)[key])
+  if (!rel && key === ".") rel = typeof manifest.main === "string" ? manifest.main : "index.js"
+  if (!rel) throw new CliError(`${manifest.name} has no export "${key}"`)
+  return join(pkgDir, rel)
+}
+
+const isNotFound = (e: unknown, spec: string): boolean => {
+  const code = (e as { code?: string })?.code
+  const msg = e instanceof Error ? e.message : String(e)
+  return (code === "ERR_MODULE_NOT_FOUND" || code === "MODULE_NOT_FOUND" || /Cannot find (module|package)/i.test(msg)) && msg.includes(spec.split("/")[0]!)
+}
+
+export type LoadPeerOptions = {
+  /** What is asking — names the command in the consent prompt / error ("lecodes render"). */
+  for: string
+  /** `false`: never install — return null when the peer is nowhere (opportunistic features). */
+  install?: boolean
+}
+
+/**
+ * Load an optional peer's subpath: the bare specifier first (global / workspace), then the CLI's
+ * prefix, else install it there (with its companions) and load. Returns null only with
+ * `install: false` and the peer absent.
+ */
+export async function loadPeer<T>(name: string, subpath: string | undefined, opts: LoadPeerOptions & { install?: true }): Promise<T>
+export async function loadPeer<T>(name: string, subpath: string | undefined, opts: LoadPeerOptions & { install: false }): Promise<T | null>
+export async function loadPeer<T>(name: string, subpath: string | undefined, opts: LoadPeerOptions): Promise<T | null> {
+  const spec = subpath ? `${name}/${subpath}` : name
+  try {
+    return (await import(spec)) as T
+  } catch (e) {
+    if (!isNotFound(e, spec)) throw e
+  }
+  const dir = peerDirInPrefix(name)
+  if (!existsSync(join(dir, "package.json"))) {
+    if (opts.install === false) return null
+    // A global install of a DIFFERENT version than the probe expects would have resolved above; here
+    // the peer is nowhere. (Globally installed but broken → the error above was not "not found".)
+    if (peerVersionGlobal(name, spec) !== null) throw new CliError(`${name} is installed but "${spec}" can't be loaded from it — reinstall it: npm install -g ${peerSpec(name)}`)
+    await installPeers(companions(name), opts.for)
+  }
+  return (await import(pathToFileURL(resolveEntry(dir, subpath)).href)) as T
+}

package/src/peers.ts

@@ -1,26 +1,49 @@
 import { existsSync, readFileSync } from "node:fs"
 import { createRequire } from "node:module"
-import { dirname, join } from "node:path"
-
-/* Optional peer packages a user installs separately — `npm install -g …`, matching how the CLI
- * itself is installed. A bare specifier resolves upward from the importing FILE, so a global CLI
- * only ever sees globally installed peers: a project-local `-D` install is invisible to it, and
- * under `npx` neither works (pass every peer as its own `-p`). `--version` reports each one's
- * installed version so a stale/mismatched copy — the usual cause of "needs X" errors or silent
- * render failures like a design screen coming back empty — is visible at a glance. The probe is an
- * export subpath that resolves to a real file in BOTH the published package and the workspace
- * source, so version reporting works whether the CLI runs from npm or straight from the monorepo. */
+import { homedir } from "node:os"
+import { dirname, join, resolve } from "node:path"
+
+/* Optional peer packages the CLI loads lazily. Two places they can live:
+ *
+ *   global   `npm install -g …`, next to a globally installed CLI — the original way. A bare specifier
+ *            resolves upward from the importing FILE, so a global CLI only ever sees globally installed
+ *            peers (a project-local `-D` install is invisible to it).
+ *   prefix   ~/.lecodes/peers (LECODES_PEERS_DIR) — the CLI's own install dir, filled ON FIRST USE by
+ *            peerInstall.ts when a command needs a peer that isn't there: no admin rights, and the
+ *            runtime-set peer (lecodes-renderer) is pinned to THIS CLI's version, so the compiler and
+ *            the headless host can't drift apart. `@napi-rs/canvas` (PNG output) rides along with it.
+ *
+ * Global wins when both exist (it is what the user chose by hand). `--version` reports each peer's
+ * installed version + where it came from, so a stale/mismatched copy — the usual cause of "needs X"
+ * errors or a design screen rendering empty — is visible at a glance. The probe is an export subpath
+ * that resolves to a real file in BOTH the published package and the workspace source. */
 export const OPTIONAL_PEERS: [name: string, probe: string][] = [
   ["lecodes-renderer", "lecodes-renderer/headless"],
   ["lecodes-design", "lecodes-design/server"],
   ["lecodes-3d-editor", "lecodes-3d-editor/server"],
   ["lecodes-assets", "lecodes-assets/cli"],
+  ["@napi-rs/canvas", "@napi-rs/canvas"],
 ]
 
-/** Installed version of an optional peer, or null when it isn't installed. Resolves the probe
- *  subpath, then walks up to the nearest package.json that actually names the package (skipping any
- *  nested ones). Never throws — a standalone binary with no node_modules reports every peer absent. */
-export const peerVersion = (name: string, probe: string): string | null => {
+/** The CLI's own peer install dir. */
+export const peersDir = (): string =>
+  process.env.LECODES_PEERS_DIR ? resolve(process.env.LECODES_PEERS_DIR) : join(homedir(), ".lecodes", "peers")
+
+/** Where a peer sits inside the prefix (scoped names span two directories). */
+export const peerDirInPrefix = (name: string): string => join(peersDir(), "node_modules", ...name.split("/"))
+
+const readVersion = (dir: string): string | null => {
+  try {
+    return (JSON.parse(readFileSync(join(dir, "package.json"), "utf8")) as { version?: string }).version ?? "unknown"
+  } catch {
+    return null
+  }
+}
+
+/** Installed version of a peer as a bare specifier resolves it (global / workspace), or null. Resolves
+ *  the probe subpath, then walks up to the nearest package.json that actually names the package
+ *  (skipping any nested ones). Never throws — a standalone binary with no node_modules reports absent. */
+export const peerVersionGlobal = (name: string, probe: string): string | null => {
   try {
     const require = createRequire(import.meta.url)
     let dir = dirname(require.resolve(probe))
@@ -38,3 +61,14 @@ export const peerVersion = (name: string, probe: string): string | null => {
   return null
 }
 
+/** Installed version of a peer in the CLI's own prefix, or null. */
+export const peerVersionPrefix = (name: string): string | null => readVersion(peerDirInPrefix(name))
+
+/** Installed version of a peer wherever it lives (global first), or null when it isn't installed. */
+export const peerVersion = (name: string, probe: string): string | null =>
+  peerVersionGlobal(name, probe) ?? peerVersionPrefix(name)
+
+/** Which install a bare load of the peer would hit: "global" (npm -g / the workspace), "prefix"
+ *  (~/.lecodes/peers), or null when it is nowhere. */
+export const peerSource = (name: string, probe: string): "global" | "prefix" | null =>
+  peerVersionGlobal(name, probe) !== null ? "global" : peerVersionPrefix(name) !== null ? "prefix" : null

package/src/projectEnv.ts

@@ -69,7 +69,11 @@ export const applyDotEnv = (
 /** The nearest project root at or above `start`: the first dir with app.json or .lecodes/. */
 export const findEnvRoot = (start: string): string | null => {
   let dir = resolve(start)
+  // The home dir holds the CLI's own ~/.lecodes (matc, desktop host, peers) — never a project, and a
+  // `~/.env` must not be loaded as one (update.ts's findProjectDir draws the same line).
+  const home = resolve(homedir())
   while (true) {
+    if (dir === home) return null
     if (existsSync(join(dir, "app.json")) || existsSync(join(dir, ".lecodes"))) return dir
     const parent = dirname(dir)
     if (parent === dir) return null

package/src/releases.ts

@@ -43,6 +43,22 @@ export const semverNewer = (a: string, b: string): number => {
   return 0
 }
 
+/**
+ * The newest published version that actually carries a build for this platform — NOT the product's
+ * `latest`. A release ships the platforms whose machine ran it: matc 1.4.0 is windows-x64 alone, and
+ * its macOS build lives on 1.3.2. Keying off `latest` therefore reports "isn't published" to everyone
+ * whose platform missed the last release, even though a perfectly good older build is right there.
+ * Null when the platform has never been published at all. (These tools are deliberately version-loose:
+ * a filamat is tied to the vendored Filament, which changes rarely — see matcTool's header.)
+ */
+export const newestForPlatform = (
+  versions: ManifestVersion[], key: string,
+): { version: string, file: ManifestFile } | null => {
+  const carrying = versions.filter((v) => v.files[key]).sort((a, b) => semverNewer(a.version, b.version))
+  const newest = carrying[0]
+  return newest ? { version: newest.version, file: newest.files[key]! } : null
+}
+
 /** One product from the release manifest (always fetched fresh — see MANIFEST_URL). */
 export const fetchReleaseProduct = async (
   product: string, label: string,