lecodes-assets 0.2.1 → 2.4.10

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lecodes-assets",
-  "version": "0.2.1",
+  "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": {
@@ -9,10 +9,12 @@
   "exports": {
     ".": {
       "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",

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]
+}

package/src/cli-kit/run.ts

@@ -0,0 +1,52 @@
+import { CliError, usageError, type Command, type Flags } from "./command"
+import { PROGRAM, renderCommand, renderRoot } from "./help"
+import { nearestFlag, parseArgs } from "./parse"
+
+// The tree walk: `unreal tex x.uasset -o y.png` → the `tex` command under `unreal`, its flags read
+// against its own declaration. stdout = the result, stderr = diagnostics (errors, warnings).
+
+export type Program = { title: string, commands: Command<any>[] }
+
+const isHelp = (a: string | undefined): boolean => a === "--help" || a === "-h" || a === "help"
+
+export const runProgram = async (program: Program, argv: string[]): Promise<number> => {
+  const [ first ] = argv
+  if (first === undefined || isHelp(first)) { console.log(renderRoot(program.title, program.commands)); return 0 }
+  const top = program.commands.find((c) => c.name === first)
+  if (!top) {
+    console.error(`✗ unknown command "${first}"\n`)
+    console.log(renderRoot(program.title, program.commands))
+    return 2
+  }
+  let cmd: Command<any> = top
+  const path = [ first ]
+  let rest = argv.slice(1)
+  // descend while the next word names a subcommand
+  for (;;) {
+    const sub: Command<any> | undefined = cmd.commands?.find((c: Command<any>) => c.name === rest[0])
+    if (!sub) break
+    cmd = sub
+    path.push(rest[0])
+    rest = rest.slice(1)
+  }
+  if (rest.some((a) => a === "--help" || a === "-h")) { console.log(renderCommand(cmd, path)); return 0 }
+  if (!cmd.run) { console.log(renderCommand(cmd, path)); return rest.length ? 2 : 0 }
+  try {
+    const spec = (cmd.flags ?? {}) as Flags
+    const parsed = parseArgs(spec, rest)
+    // an unknown flag is an error, not a warning: whether it takes a value cannot be known, so the word
+    // after it would be read as a positional (a second input file)
+    if (parsed.unknown.length) {
+      const notes = parsed.unknown.map((u) => { const near = nearestFlag(spec, u); return near ? `${u} (did you mean ${near}?)` : u })
+      throw usageError(`unknown flag${notes.length > 1 ? "s" : ""}: ${notes.join(", ")} — ${PROGRAM} ${path.join(" ")} --help lists them`)
+    }
+    return await cmd.run({ args: parsed.args, flags: parsed.flags, given: parsed.given, argv: rest, path })
+  } catch (e) {
+    const err = e as Error
+    console.error(`✗ ${err?.message ?? e}`)
+    if (!(e instanceof CliError)) { if (process.env.LECODES_DEBUG && err?.stack) console.error(err.stack); return 1 }
+    // a wrong command line gets the command's own page, not the whole manual
+    if (e.showHelp) console.log(`\n${renderCommand(cmd, path)}`)
+    return e.code
+  }
+}