lecodes-assets 0.2.0 → 2.4.10

package/package.json

@@ -1,17 +1,29 @@
 {
   "name": "lecodes-assets",
-  "version": "0.2.0",
+  "version": "2.4.10",
   "description": "LeCodes asset pipeline: FBX → GLB (ufbx), clip merging by bone name, texture embedding, GLB doctor (bone cap, texture normalize, KTX2).",
   "type": "module",
   "bin": {
     "lecodes-assets": "dist/cli.js"
   },
   "exports": {
-    ".": { "types": "./src/index.ts", "default": "./dist/index.js" },
-    "./cli": { "types": "./src/cli.ts", "default": "./dist/cli.js" }
+    ".": {
+      "types": "./src/index.ts",
+      "bun": "./src/index.ts",
+      "default": "./dist/index.js"
+    },
+    "./cli": {
+      "types": "./src/cli.ts",
+      "bun": "./src/cli.ts",
+      "default": "./dist/cli.js"
+    },
+    "./fbx/*": "./src/fbx/*.ts",
+    "./retarget/*": "./src/retarget/*.ts",
+    "./unreal/*": "./src/unreal/*.ts"
   },
   "files": [
     "dist",
+    "src",
     "README.md"
   ],
   "engines": {

package/src/bvh/fromDocument.ts

@@ -0,0 +1,136 @@
+// glTF document → BVH: one clip of a skeleton (a rig the BVH reader made, or any rig whose nodes ARE
+// the joints) written in the layout Kimodo reads back (`kimodo_convert x.bvh x.npz
+// --bvh_standard_tpose`): a zero `Root` with six channels over the root joint (six channels), every
+// other joint three ZYX rotation channels, no End Sites, centimetres, the rest pose = the nodes'
+// rest translations (their offsets) with identity rotations — i.e. the file's rest is whatever the
+// document's rest is (the standard T-pose for a rig read from Kimodo's `--bvh_standard_tpose` export).
+// The clip is resampled at `fps` (nlerp between keys).
+
+import type { Document, Node } from "@gltf-transform/core"
+
+type Quat = [number, number, number, number]
+type Vec3 = [number, number, number]
+
+export type BvhWriteOptions = {
+  /** the clip to write (default: the document's first) */
+  clip?: string
+  /** frames per second of the output (default 30 — Kimodo's rate) */
+  fps?: number
+  /** metres per BVH unit (default 0.01: centimetres) */
+  unit?: number
+  /** the wrapper root's name over the skeleton root (default "Root"); "" = none, the skeleton root is the BVH root */
+  wrapperRoot?: string
+}
+
+const nlerp = (a: Quat, b: Quat, t: number): Quat => {
+  const d = a[0] * b[0] + a[1] * b[1] + a[2] * b[2] + a[3] * b[3]
+  const s = d < 0 ? -1 : 1
+  const q: Quat = [ a[0] + (s * b[0] - a[0]) * t, a[1] + (s * b[1] - a[1]) * t, a[2] + (s * b[2] - a[2]) * t, a[3] + (s * b[3] - a[3]) * t ]
+  const n = Math.hypot(q[0], q[1], q[2], q[3]) || 1
+  return [ q[0] / n, q[1] / n, q[2] / n, q[3] / n ]
+}
+
+/** Z·Y·X Euler angles (degrees, in channel order Zrotation Yrotation Xrotation) of a unit quaternion:
+ *  R = Rz(γ)·Ry(β)·Rx(α) → β = asin(−R20), α = atan2(R21, R22), γ = atan2(R10, R00). */
+const eulerZYX = (q: Quat): [number, number, number] => {
+  const [ x, y, z, w ] = q
+  const r00 = 1 - 2 * (y * y + z * z), r10 = 2 * (x * y + z * w), r20 = 2 * (x * z - y * w)
+  const r21 = 2 * (y * z + x * w), r22 = 1 - 2 * (x * x + y * y)
+  const b = Math.asin(Math.max(-1, Math.min(1, -r20)))
+  const D = 180 / Math.PI
+  if (Math.abs(r20) > 0.999999) {
+    // gimbal lock: fold everything into γ
+    const r01 = 2 * (x * y - z * w), r11 = 1 - 2 * (x * x + z * z)
+    return [ Math.atan2(-r01, r11) * D, b * D, 0 ]
+  }
+  return [ Math.atan2(r10, r00) * D, b * D, Math.atan2(r21, r22) * D ]
+}
+
+const f = (v: number): string => {
+  const s = (Math.abs(v) < 5e-7 ? 0 : v).toFixed(6)
+  return s.replace(/\.?0+$/, "") || "0"
+}
+
+export const documentToBvh = (doc: Document, opts: BvhWriteOptions = {}): { text: string, report: { clip: string, joints: number, frames: number, fps: number } } => {
+  const fps = opts.fps ?? 30
+  const U = opts.unit ?? 0.01
+  const root = doc.getRoot()
+  const anim = opts.clip ? root.listAnimations().find((a) => a.getName() === opts.clip) : root.listAnimations()[0]
+  if (!anim) throw new Error(opts.clip ? `no clip "${opts.clip}" (have ${root.listAnimations().map((a) => a.getName()).join(", ")})` : "no animation in the document")
+
+  // the skeleton: the joints of the first skin if there is one, else every node under the scene
+  const skin = root.listSkins()[0]
+  const joints = skin ? skin.listJoints() : root.listNodes().filter((n) => !n.getMesh())
+  const jointSet = new Set(joints)
+  const skelRoots = joints.filter((n) => { const p = n.getParentNode(); return !p || !jointSet.has(p) })
+  if (skelRoots.length !== 1) throw new Error(`the skeleton must have one root joint (found ${skelRoots.map((n) => n.getName()).join(", ") || "none"})`)
+  const skelRoot = skelRoots[0]
+
+  // tracks: per joint, the sampler for rotation / translation
+  const tracks = new Map<Node, { rot?: { t: Float32Array, v: Float32Array }, pos?: { t: Float32Array, v: Float32Array } }>()
+  for (const ch of anim.listChannels()) {
+    const node = ch.getTargetNode(), s = ch.getSampler()
+    if (!node || !s || !jointSet.has(node)) continue
+    const t = s.getInput()?.getArray() as Float32Array | undefined, v = s.getOutput()?.getArray() as Float32Array | undefined
+    if (!t || !v) continue
+    const rec = tracks.get(node) ?? {}
+    if (ch.getTargetPath() === "rotation") rec.rot = { t, v }
+    else if (ch.getTargetPath() === "translation") rec.pos = { t, v }
+    tracks.set(node, rec)
+  }
+  let duration = 0
+  for (const r of tracks.values()) for (const k of [ r.rot, r.pos ]) if (k) duration = Math.max(duration, k.t[k.t.length - 1])
+  const frames = Math.max(1, Math.round(duration * fps) + 1)
+
+  const sample = (t: Float32Array, v: Float32Array, n: number, time: number, mix: (a: number[], b: number[], k: number) => number[]): number[] => {
+    if (time <= t[0]) return Array.from(v.subarray(0, n))
+    const last = t.length - 1
+    if (time >= t[last]) return Array.from(v.subarray(last * n, last * n + n))
+    let i = 0
+    while (i < last && t[i + 1] <= time) i++
+    const k = (time - t[i]) / Math.max(1e-9, t[i + 1] - t[i])
+    return mix(Array.from(v.subarray(i * n, i * n + n)), Array.from(v.subarray((i + 1) * n, (i + 1) * n + n)), k)
+  }
+  const mixV = (a: number[], b: number[], k: number): number[] => a.map((x, i) => x + (b[i] - x) * k)
+  const mixQ = (a: number[], b: number[], k: number): number[] => nlerp(a as Quat, b as Quat, k)
+
+  // the hierarchy
+  const order: Node[] = []
+  const lines: string[] = [ "HIERARCHY" ]
+  const wrapper = opts.wrapperRoot ?? "Root"
+  const emit = (n: Node, depth: number, isRoot: boolean): void => {
+    order.push(n)
+    const pad = "  ".repeat(depth)
+    const o = n.getTranslation()
+    lines.push(`${pad}${isRoot && !wrapper ? "ROOT" : "JOINT"} ${n.getName()}`)
+    lines.push(`${pad}{`)
+    lines.push(`${pad}  OFFSET ${f(o[0] / U)} ${f(o[1] / U)} ${f(o[2] / U)}`)
+    lines.push(`${pad}  CHANNELS ${isRoot ? "6 Xposition Yposition Zposition " : "3 "}Zrotation Yrotation Xrotation`)
+    for (const c of n.listChildren()) if (jointSet.has(c)) emit(c, depth + 1, false)
+    lines.push(`${pad}}`)
+  }
+  if (wrapper) {
+    lines.push(`ROOT ${wrapper}`, "{", "  OFFSET 0.0 0.0 0.0", "  CHANNELS 6 Xposition Yposition Zposition Zrotation Yrotation Xrotation")
+    emit(skelRoot, 1, true)
+    lines.push("}")
+  } else emit(skelRoot, 0, true)
+
+  lines.push("MOTION", `Frames: ${frames}`, `Frame Time: ${1 / fps}`)
+  for (let fi = 0; fi < frames; fi++) {
+    const time = fi / fps
+    const row: string[] = []
+    if (wrapper) row.push("0.0 0.0 0.0 0.0 0.0 0.0")
+    order.forEach((n, i) => {
+      const tr = tracks.get(n)
+      if (i === 0) {
+        const p = tr?.pos ? sample(tr.pos.t, tr.pos.v, 3, time, mixV) : Array.from(n.getTranslation())
+        row.push(f(p[0] / U), f(p[1] / U), f(p[2] / U))
+      }
+      const q = (tr?.rot ? sample(tr.rot.t, tr.rot.v, 4, time, mixQ) : Array.from(n.getRotation())) as Quat
+      const [ z, y, x ] = eulerZYX(q)
+      row.push(f(z), f(y), f(x))
+    })
+    lines.push(row.join(" "))
+  }
+  return { text: lines.join("\n") + "\n", report: { clip: anim.getName(), joints: order.length, frames, fps } }
+}

package/src/bvh/toDocument.ts

@@ -0,0 +1,202 @@
+// BVH → glTF document: a skeleton-only rig (nodes + a skin with inverse binds, no mesh) carrying the
+// file's motion as one animation clip — what `retarget --from <clip>.bvh` and `convert <clip>.bvh`
+// read. Written for Kimodo's SOMA export (`kimodo_gen --bvh --bvh_standard_tpose` / `kimodo_convert
+// … .bvh --bvh_standard_tpose`: centimetres, Y-up, a zero `Root` above `Hips`, ZYX Euler channels,
+// the rest pose = the standard T-pose), but the parser is plain BVH.
+//
+// Conventions taken: OFFSET = the joint's rest translation; a joint's own position channels REPLACE
+// its offset (bvhio / Kimodo: the T-pose file's Hips channels equal its offset); rotation channels
+// compose in the listed order (Zrotation Yrotation Xrotation → R = Rz·Ry·Rx); End Sites become
+// `<parent>_End` leaves outside the skin. A zero-offset root with a single child (Kimodo's `Root`
+// above `Hips`) is folded into that child unless `keepRoot`.
+
+import { Document } from "@gltf-transform/core"
+
+type Quat = [number, number, number, number]
+type Vec3 = [number, number, number]
+type Joint = { name: string, parent: number, offset: Vec3, channels: string[], end: boolean }
+
+export type BvhOptions = {
+  /** the clip's name (default: the file's stem) */
+  name?: string
+  /** keep a zero-offset single-child root joint instead of folding it into its child */
+  keepRoot?: boolean
+  /** the file's length unit in metres (default 0.01: centimetres, the mocap convention) */
+  unit?: number
+}
+
+export type BvhReport = {
+  joints: number
+  skinJoints: number
+  folded?: string
+  frames: number
+  fps: number
+  duration: number
+  rotationTracks: number
+  translationTracks: number
+  /** the hips' height range and horizontal travel, metres */
+  hipsY: [number, number]
+  travel: number
+}
+
+const qmul = (a: Quat, b: Quat): Quat => [
+  a[3] * b[0] + a[0] * b[3] + a[1] * b[2] - a[2] * b[1],
+  a[3] * b[1] - a[0] * b[2] + a[1] * b[3] + a[2] * b[0],
+  a[3] * b[2] + a[0] * b[1] - a[1] * b[0] + a[2] * b[3],
+  a[3] * b[3] - a[0] * b[0] - a[1] * b[1] - a[2] * b[2],
+]
+const qaxis = (axis: string, deg: number): Quat => {
+  const h = deg * Math.PI / 360, s = Math.sin(h), c = Math.cos(h)
+  return axis === "X" ? [ s, 0, 0, c ] : axis === "Y" ? [ 0, s, 0, c ] : [ 0, 0, s, c ]
+}
+const qrot = (q: Quat, v: Vec3): Vec3 => {
+  const [ x, y, z, w ] = q
+  const ix = w * v[0] + y * v[2] - z * v[1], iy = w * v[1] + z * v[0] - x * v[2], iz = w * v[2] + x * v[1] - y * v[0], iw = -x * v[0] - y * v[1] - z * v[2]
+  return [ ix * w + iw * -x + iy * -z - iz * -y, iy * w + iw * -y + iz * -x - ix * -z, iz * w + iw * -z + ix * -y - iy * -x ]
+}
+
+export const parseBvh = (text: string): { joints: Joint[], frames: number, frameTime: number, rows: number[][] } => {
+  const motionAt = text.indexOf("MOTION")
+  if (motionAt < 0) throw new Error("BVH: no MOTION section")
+  const hier = text.slice(0, motionAt).replace(/\r/g, "").split(/\s+/).filter(Boolean)
+  const joints: Joint[] = []
+  const stack: number[] = []
+  let i = 0
+  const next = (): string => hier[i++]
+  while (i < hier.length) {
+    const tok = next()
+    if (tok === "HIERARCHY") continue
+    if (tok === "ROOT" || tok === "JOINT") {
+      joints.push({ name: next(), parent: stack.length ? stack[stack.length - 1] : -1, offset: [ 0, 0, 0 ], channels: [], end: false })
+    } else if (tok === "End") {
+      next() // Site
+      joints.push({ name: `${joints[stack[stack.length - 1]].name}_End`, parent: stack[stack.length - 1], offset: [ 0, 0, 0 ], channels: [], end: true })
+    } else if (tok === "{") {
+      stack.push(joints.length - 1)
+    } else if (tok === "}") {
+      stack.pop()
+    } else if (tok === "OFFSET") {
+      joints[joints.length - 1].offset = [ +next(), +next(), +next() ]
+    } else if (tok === "CHANNELS") {
+      const n = +next()
+      for (let k = 0; k < n; k++) joints[joints.length - 1].channels.push(next())
+    }
+  }
+  const motion = text.slice(motionAt).replace(/\r/g, "").split("\n")
+  const frames = +(motion.find((l) => l.startsWith("Frames:"))?.split(":")[1] ?? 0)
+  const frameTime = +(motion.find((l) => l.startsWith("Frame Time:"))?.split(":")[1] ?? 1 / 30)
+  const dataStart = motion.findIndex((l) => l.startsWith("Frame Time:")) + 1
+  const rows = motion.slice(dataStart).map((l) => l.trim()).filter(Boolean).slice(0, frames).map((l) => l.split(/\s+/).map(Number))
+  const channelCount = joints.reduce((n, j) => n + j.channels.length, 0)
+  if (rows.length !== frames || rows.some((r) => r.length !== channelCount)) throw new Error(`BVH: motion data mismatch — ${rows.length}/${frames} frames, ${channelCount} channels per frame expected`)
+  return { joints, frames, frameTime, rows }
+}
+
+export const bvhToDocument = (text: string, opts: BvhOptions = {}): { doc: Document, report: BvhReport } => {
+  const { joints, frames, frameTime, rows } = parseBvh(text)
+  const U = opts.unit ?? 0.01
+  const clipName = opts.name ?? "bvh"
+
+  // per frame, per joint: local translation (m) and rotation
+  const local = rows.map((row) => {
+    let c = 0
+    return joints.map((j) => {
+      const t: Vec3 = [ j.offset[0] * U, j.offset[1] * U, j.offset[2] * U ]
+      let q: Quat = [ 0, 0, 0, 1 ]
+      let hasPos = false
+      for (const ch of j.channels) {
+        const v = row[c++]
+        if (ch === "Xposition") { t[0] = v * U; hasPos = true } else if (ch === "Yposition") { t[1] = v * U; hasPos = true } else if (ch === "Zposition") { t[2] = v * U; hasPos = true }
+        else if (ch.endsWith("rotation")) q = qmul(q, qaxis(ch[0], v))
+      }
+      return { t, q, hasPos }
+    })
+  })
+
+  // fold a zero-offset, single-child root into its child (Kimodo's `Root` above `Hips`)
+  let dropped = -1
+  let folded: string | undefined
+  if (!opts.keepRoot && joints[0].parent === -1 && joints.filter((j) => j.parent === 0).length === 1 && joints[0].offset.every((v) => v === 0)) {
+    const child = joints.findIndex((j) => j.parent === 0)
+    for (const f of local) {
+      const r = f[0], h = f[child]
+      const t = qrot(r.q, h.t)
+      f[child] = { t: [ r.t[0] + t[0], r.t[1] + t[1], r.t[2] + t[2] ], q: qmul(r.q, h.q), hasPos: true }
+    }
+    joints[child].parent = -1
+    dropped = 0
+    folded = `${joints[0].name} → ${joints[child].name}`
+  }
+
+  const doc = new Document()
+  const buffer = doc.createBuffer()
+  const scene = doc.createScene("Scene")
+  const nodes = joints.map((j, i) => i === dropped ? null : doc.createNode(j.name).setTranslation([ j.offset[0] * U, j.offset[1] * U, j.offset[2] * U ]))
+  const worldRest: Vec3[] = joints.map(() => [ 0, 0, 0 ])
+  joints.forEach((j, i) => {
+    if (i === dropped) return
+    const p = j.parent
+    const pw = p >= 0 && p !== dropped ? worldRest[p] : [ 0, 0, 0 ]
+    worldRest[i] = [ pw[0] + j.offset[0] * U, pw[1] + j.offset[1] * U, pw[2] + j.offset[2] * U ]
+    if (p >= 0 && p !== dropped) nodes[p]!.addChild(nodes[i]!); else scene.addChild(nodes[i]!)
+  })
+
+  // the skin: every non-end joint, inverse binds from the rest pose (offsets only — pure translations)
+  const armature = doc.createNode("Armature")
+  scene.addChild(armature)
+  const skin = doc.createSkin("bvh")
+  const skinJoints = joints.map((_, i) => i).filter((i) => i !== dropped && !joints[i].end)
+  const ibm = new Float32Array(skinJoints.length * 16)
+  skinJoints.forEach((ji, k) => {
+    const o = k * 16
+    ibm[o] = 1; ibm[o + 5] = 1; ibm[o + 10] = 1; ibm[o + 15] = 1
+    ibm[o + 12] = -worldRest[ji][0]; ibm[o + 13] = -worldRest[ji][1]; ibm[o + 14] = -worldRest[ji][2]
+    skin.addJoint(nodes[ji]!)
+  })
+  skin.setInverseBindMatrices(doc.createAccessor("ibm").setType("MAT4").setArray(ibm).setBuffer(buffer))
+  skin.setSkeleton(nodes[joints.findIndex((j, i) => i !== dropped && (j.parent === -1 || j.parent === dropped))]!)
+  armature.setSkin(skin)
+
+  // the clip
+  const anim = doc.createAnimation(clipName)
+  const times = new Float32Array(frames)
+  for (let f = 0; f < frames; f++) times[f] = f * frameTime
+  const timeAcc = doc.createAccessor("time").setType("SCALAR").setArray(times).setBuffer(buffer)
+  let rotationTracks = 0, translationTracks = 0
+  joints.forEach((j, i) => {
+    if (i === dropped || j.end) return
+    if (j.channels.some((c) => c.endsWith("rotation"))) {
+      const out = new Float32Array(frames * 4)
+      let prev: Quat = [ 0, 0, 0, 1 ]
+      for (let f = 0; f < frames; f++) {
+        let q = local[f][i].q
+        if (q[0] * prev[0] + q[1] * prev[1] + q[2] * prev[2] + q[3] * prev[3] < 0) q = [ -q[0], -q[1], -q[2], -q[3] ]
+        out.set(q, f * 4); prev = q
+      }
+      const s = doc.createAnimationSampler().setInput(timeAcc).setOutput(doc.createAccessor().setType("VEC4").setArray(out).setBuffer(buffer)).setInterpolation("LINEAR")
+      anim.addSampler(s).addChannel(doc.createAnimationChannel().setTargetNode(nodes[i]!).setTargetPath("rotation").setSampler(s))
+      rotationTracks++
+    }
+    if (local.some((f) => f[i].hasPos)) {
+      const out = new Float32Array(frames * 3)
+      for (let f = 0; f < frames; f++) out.set(local[f][i].t, f * 3)
+      const s = doc.createAnimationSampler().setInput(timeAcc).setOutput(doc.createAccessor().setType("VEC3").setArray(out).setBuffer(buffer)).setInterpolation("LINEAR")
+      anim.addSampler(s).addChannel(doc.createAnimationChannel().setTargetNode(nodes[i]!).setTargetPath("translation").setSampler(s))
+      translationTracks++
+    }
+  })
+
+  const hipsI = Math.max(0, joints.findIndex((j, i) => i !== dropped && (j.parent === -1 || j.parent === dropped)))
+  const hipY = local.map((f) => f[hipsI].t[1])
+  const a = local[0][hipsI].t, b = local[frames - 1][hipsI].t
+  return {
+    doc,
+    report: {
+      joints: joints.length - (dropped >= 0 ? 1 : 0), skinJoints: skinJoints.length, folded, frames, fps: 1 / frameTime, duration: frames * frameTime,
+      rotationTracks, translationTracks, hipsY: [ Math.min(...hipY), Math.max(...hipY) ], travel: Math.hypot(b[0] - a[0], b[2] - a[2]),
+    },
+  }
+}
+
+export const describeBvh = (r: BvhReport): string =>
+  `${r.joints} joints (${r.skinJoints} in the skin${r.folded ? `, ${r.folded} folded` : ""}), ${r.frames} frames @ ${r.fps.toFixed(1)} fps = ${r.duration.toFixed(2)} s · ${r.rotationTracks} rotation + ${r.translationTracks} translation tracks · hips y ${r.hipsY[0].toFixed(3)}…${r.hipsY[1].toFixed(3)} m · travel ${r.travel.toFixed(2)} m`

package/src/cli-kit/command.ts

@@ -0,0 +1,100 @@
+/*
+ * A command is DATA: its name, one summary line, the flags it takes, its subcommands, and `run`.
+ * The parser (parse.ts) reads the argv AGAINST that declaration — which flag takes a value, which
+ * takes several, which may stand alone — so a flag the code reads and the parser does not know
+ * cannot exist, and the help (help.ts) is rendered from the same data. The shape follows
+ * lecodes-cli's `src/cli` (this package stays standalone, so it carries its own small copy).
+ *
+ *   export default defineCommand({
+ *     name: "mirror",
+ *     summary: "Add mirrored copies of clips (left ↔ right)",
+ *     usage: "<model.glb>",
+ *     flags: {
+ *       clips: list("only these clips", { value: "a b …" }),
+ *       suffix: str("appended to the mirrored clip's name", { value: "_M" }),
+ *       o: str("output (default: in place)", { value: "out.glb" }),
+ *     },
+ *     run: async ({ args, flags }) => { … flags.clips: string[], flags.suffix: string | undefined … return 0 },
+ *   })
+ *
+ * Flag names are their command-line spelling without the dashes (`"clip-names"`, `"o"` for `-o`);
+ * read them as `flags["clip-names"]`. Groups of flags several commands share are plain objects
+ * spread into `flags:` (see `../commands/shared.ts`).
+ */
+
+type Base = {
+  help: string
+  /** The placeholder shown in help (`<file>`, `N`). */
+  value?: string
+  /** A heading the help prints above this flag (and the ones after it, until the next heading). */
+  group?: string
+}
+
+export type FlagSpec =
+  | Base & { type: "string", /** value when the flag stands alone (`--split` next to `--split dir`) */ bare?: string }
+  | Base & { type: "number", bare?: number, integer?: boolean, /** must be > 0 */ positive?: boolean }
+  | Base & { type: "boolean" }
+  | Base & { type: "list" }
+
+export type Flags = Record<string, FlagSpec>
+
+type Opts = { value?: string, group?: string }
+/** A string-valued flag (`-o out.glb`). `bare` lets it stand alone and names what it then reads as. */
+export const str = (help: string, opts?: Opts & { bare?: string }): FlagSpec & { type: "string" } => ({ type: "string", help, ...opts })
+/** A numeric flag, parsed and validated (`--scale 0.01`); `integer` / `positive` narrow it. */
+export const num = (help: string, opts?: Opts & { bare?: number, integer?: boolean, positive?: boolean }): FlagSpec & { type: "number" } => ({ type: "number", help, ...opts })
+/** A whole number (`--max-size 1024`). */
+export const int = (help: string, opts?: Opts & { bare?: number, positive?: boolean }): FlagSpec & { type: "number" } => ({ type: "number", help, integer: true, ...opts })
+/** A switch (`--force`). */
+export const bool = (help: string, opts?: { group?: string }): FlagSpec & { type: "boolean" } => ({ type: "boolean", help, ...opts })
+/** A flag that takes every value up to the next flag (`--clips a.fbx b.fbx`); repeats accumulate. */
+export const list = (help: string, opts?: Opts): FlagSpec & { type: "list" } => ({ type: "list", help, ...opts })
+
+type ValueOf<S extends FlagSpec> =
+  S extends { type: "boolean" } ? boolean
+  : S extends { type: "list" } ? string[]
+  : S extends { type: "number" } ? number | undefined
+  : string | undefined
+
+export type FlagValues<F extends Flags> = { [K in keyof F]: ValueOf<F[K]> }
+
+export type Context<F extends Flags = Flags> = {
+  /** Positional arguments after the command path. */
+  args: string[]
+  /** The declared flags, typed and validated. */
+  flags: FlagValues<F>
+  /** Which declared flags were on the line at all (a `bare` flag reads the same as its default). */
+  given: Set<keyof F & string>
+  /** The argv after the command path, untouched. */
+  argv: string[]
+  /** The command path that was run (`["unreal", "tex"]`). */
+  path: string[]
+}
+
+export type Command<F extends Flags = Flags> = {
+  name: string
+  /** One line for the command list. */
+  summary: string
+  /** The positional syntax after the name: `"<model.glb>"`. Omit for none. */
+  usage?: string
+  /** Paragraphs for `<name> --help`; blank lines separate paragraphs. */
+  description?: string
+  flags?: F
+  commands?: Command<any>[]
+  examples?: string[]
+  /** What runs; resolves to the exit code. A command with subcommands and no `run` prints its help. */
+  run?: (ctx: Context<F>) => Promise<number> | number
+}
+
+export const defineCommand = <F extends Flags>(cmd: Command<F>): Command<F> => cmd
+
+/** A failure with its exit code: 1 = the work failed, 2 = the command line is wrong. The runner prints `✗ message`. */
+export class CliError extends Error {
+  constructor(message: string, readonly code = 1, /** print the command's help page after the message */ readonly showHelp = false) { super(message) }
+}
+/** The command line is wrong (exit 2). */
+export const usageError = (message: string): CliError => new CliError(message, 2)
+/** Something the command cannot start without is missing (exit 2, followed by the command's help). */
+export const missing = (what: string): CliError => new CliError(`missing ${what}`, 2, true)
+/** The input path does not exist (exit 1). */
+export const notFound = (path: string): CliError => new CliError(`not found: ${path}`)

package/src/cli-kit/help.ts

@@ -0,0 +1,72 @@
+import type { Command, FlagSpec } from "./command"
+import { spell } from "./parse"
+
+// Two levels, both rendered from the command declarations: the command list (bare call / --help at
+// the top) and one command's page (`<command> --help`, and what a usage error prints).
+
+const WIDTH = 100
+const wrap = (text: string, indent: number): string[] => {
+  const room = Math.max(30, WIDTH - indent)
+  const out: string[] = []
+  for (const para of text.split("\n")) {
+    let line = ""
+    for (const word of para.split(/\s+/).filter(Boolean)) {
+      if (line && line.length + 1 + word.length > room) { out.push(line); line = word } else line = line ? `${line} ${word}` : word
+    }
+    out.push(line)
+  }
+  return out
+}
+
+const flagLabel = (name: string, s: FlagSpec): string => {
+  if (s.type === "boolean") return spell(name)
+  const value = s.value ?? (s.type === "number" ? "N" : s.type === "list" ? "a b …" : "<value>")
+  return `${spell(name)} ${"bare" in s && s.bare !== undefined ? `[${value}]` : value}`
+}
+
+const rows = (pairs: [string, string][], indent: number, column: number): string[] => {
+  const out: string[] = []
+  const pad = " ".repeat(indent)
+  for (const [ label, help ] of pairs) {
+    const lines = wrap(help, indent + column)
+    if (label.length < column - 1) out.push(`${pad}${label.padEnd(column)}${lines[0] ?? ""}`)
+    else { out.push(`${pad}${label}`); out.push(`${pad}${" ".repeat(column)}${lines[0] ?? ""}`) }
+    for (const l of lines.slice(1)) out.push(`${pad}${" ".repeat(column)}${l}`)
+  }
+  return out
+}
+
+export const PROGRAM = "lecodes assets"
+
+/** The command list. */
+export const renderRoot = (title: string, commands: Command<any>[]): string => [
+  title,
+  "",
+  `Usage: ${PROGRAM} <command> [args…]      (${PROGRAM} <command> --help for its flags)`,
+  "",
+  ...rows(commands.map((c) => [ c.name, c.summary ]), 2, 16),
+].join("\n")
+
+/** One command's page: syntax, description, subcommands, flags by group, examples. */
+export const renderCommand = (cmd: Command<any>, path: string[]): string => {
+  const out: string[] = []
+  const full = `${PROGRAM} ${path.join(" ")}`
+  out.push(`${full}${cmd.commands?.length ? " <command>" : ""}${cmd.usage ? ` ${cmd.usage}` : ""}${cmd.flags && Object.keys(cmd.flags).length ? " [flags]" : ""}`)
+  out.push("", ...wrap(cmd.summary, 2).map((l) => `  ${l}`))
+  if (cmd.description) for (const para of cmd.description.trim().split(/\n\s*\n/)) out.push("", ...wrap(para.replace(/\s*\n\s*/g, " "), 2).map((l) => `  ${l}`))
+  if (cmd.commands?.length) out.push("", "Commands:", ...rows(cmd.commands.map((c) => [ `${c.name}${c.usage ? ` ${c.usage}` : ""}`, c.summary ]), 2, 30))
+  const flags = Object.entries((cmd.flags ?? {}) as Record<string, FlagSpec>)
+  if (flags.length) {
+    let group: string | undefined
+    let batch: [string, string][] = []
+    const flush = (): void => { if (batch.length) out.push(...rows(batch, 2, 30)); batch = [] }
+    out.push("", "Flags:")
+    for (const [ name, s ] of flags) {
+      if (s.group !== undefined && s.group !== group) { flush(); group = s.group; out.push("", `  ${group}`) }
+      batch.push([ flagLabel(name, s), s.help ])
+    }
+    flush()
+  }
+  if (cmd.examples?.length) out.push("", "Examples:", ...cmd.examples.map((e) => `  ${e}`))
+  return out.join("\n")
+}

package/src/cli-kit/index.ts

@@ -0,0 +1,4 @@
+export { defineCommand, str, num, int, bool, list, CliError, usageError, missing, notFound } from "./command"
+export type { Command, Context, Flags, FlagSpec, FlagValues } from "./command"
+export { runProgram } from "./run"
+export type { Program } from "./run"

package/src/cli-kit/parse.ts

@@ -0,0 +1,72 @@
+import { usageError, type Flags, type FlagSpec, type FlagValues } from "./command"
+
+// `--region -10,0,50,60` / `--scale -1`: "-" + digit is a negative number, not the next flag.
+const isValue = (s: string): boolean => !s.startsWith("-") || /^-(\d|\.\d)/.test(s)
+const flagName = (a: string): string => a.replace(/^--?/, "")
+/** How a flag is spelled on the line: one letter takes one dash. */
+export const spell = (name: string): string => (name.length === 1 ? `-${name}` : `--${name}`)
+
+export type ParsedArgs<F extends Flags> = { args: string[], flags: FlagValues<F>, given: Set<keyof F & string>, unknown: string[] }
+
+const readNumber = (name: string, s: FlagSpec & { type: "number" }, text: string): number => {
+  const n = Number(text)
+  if (!Number.isFinite(n)) throw usageError(`${spell(name)} needs a number, got "${text}"`)
+  if (s.integer && !Number.isInteger(n)) throw usageError(`${spell(name)} needs a whole number, got "${text}"`)
+  if (s.positive && n <= 0) throw usageError(`${spell(name)} needs a positive number, got "${text}"`)
+  return n
+}
+
+/** Read an argv against a flag declaration. Unknown flags are collected (the runner warns), never
+ *  guessed at: an undeclared `--x 4` used to leave `4` behind as a positional. */
+export const parseArgs = <F extends Flags>(spec: F, argv: string[]): ParsedArgs<F> => {
+  const args: string[] = []
+  const unknown: string[] = []
+  const given = new Set<string>()
+  const out: Record<string, unknown> = {}
+  for (const [ name, s ] of Object.entries(spec)) out[name] = s.type === "boolean" ? false : s.type === "list" ? [] : undefined
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i]
+    if (isValue(a)) { args.push(a); continue }
+    const name = flagName(a)
+    const s = spec[name]
+    if (!s || spell(name) !== a) { unknown.push(a); continue }
+    given.add(name)
+    if (s.type === "boolean") { out[name] = true; continue }
+    if (s.type === "list") {
+      const values = out[name] as string[]
+      while (i + 1 < argv.length && isValue(argv[i + 1])) values.push(argv[++i])
+      continue
+    }
+    const next = i + 1 < argv.length && isValue(argv[i + 1]) ? argv[++i] : undefined
+    if (next === undefined) {
+      if (s.bare === undefined) throw usageError(`${a} needs a value${s.value ? ` (${s.value})` : ""}`)
+      out[name] = s.bare
+    } else out[name] = s.type === "number" ? readNumber(name, s, next) : next
+  }
+  return { args, flags: out as FlagValues<F>, given: given as Set<keyof F & string>, unknown }
+}
+
+/** The declared flag closest to a misspelled one (edit distance ≤ 2), for the warning. */
+export const nearestFlag = (spec: Flags, typed: string): string | undefined => {
+  const want = flagName(typed)
+  let best: string | undefined, bd = 3
+  for (const name of Object.keys(spec)) {
+    const d = distance(want, name)
+    if (d < bd) { bd = d; best = name }
+  }
+  return best ? spell(best) : undefined
+}
+
+const distance = (a: string, b: string): number => {
+  const row = Array.from({ length: b.length + 1 }, (_, i) => i)
+  for (let i = 1; i <= a.length; i++) {
+    let prev = row[0]
+    row[0] = i
+    for (let j = 1; j <= b.length; j++) {
+      const cur = row[j]
+      row[j] = Math.min(row[j] + 1, row[j - 1] + 1, prev + (a[i - 1] === b[j - 1] ? 0 : 1))
+      prev = cur
+    }
+  }
+  return row[b.length]
+}