{"_id":"@dogsvr/cfg-luban-cli","_rev":"2-b1cf84e0160407f6c977a13e41ab47b4","name":"@dogsvr/cfg-luban-cli","dist-tags":{"latest":"0.4.1"},"versions":{"0.4.0":{"name":"@dogsvr/cfg-luban-cli","version":"0.4.0","keywords":["dogsvr","game-config","luban","flatbuffers","lmdb","codegen","cli"],"author":{"name":"rowanzhu"},"license":"MIT","_id":"@dogsvr/cfg-luban-cli@0.4.0","maintainers":[{"name":"rowanzhu","email":"rowanzhu@gmail.com"}],"homepage":"https://github.com/dogsvr/cfg-luban#readme","bugs":{"url":"https://github.com/dogsvr/cfg-luban/issues"},"bin":{"cfg-luban-cli":"dist/cli.js"},"dist":{"shasum":"5135deeb36e2480c3566e2480031daebb086f8b2","tarball":"https://registry.npmjs.org/@dogsvr/cfg-luban-cli/-/cfg-luban-cli-0.4.0.tgz","fileCount":18,"integrity":"sha512-p3qCDYg8R6hMiubBiWsGXdSualrdwavSuc322CeCxAjzaiTZb5H3zGABXmQjaplYZcA0DIDLJY+KZS3r5wq4iQ==","signatures":[{"sig":"MEYCIQCyI5S6a2bBlOIeEOyptosHXcr66IzgmlOvZBN/jCoCigIhALTKG5RtmyHwUjyoJtYieMSTjl4FRncg4VN0gbmn/8rp","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":50479},"main":"./dist/pipeline.js","types":"./dist/pipeline.d.ts","exports":{".":{"types":"./dist/pipeline.d.ts","default":"./dist/pipeline.js"},"./package.json":"./package.json"},"gitHead":"2027c070a71f44e0e1a5848143180a37cccfed93","scripts":{"build":"rm -rf dist && tsc && chmod +x dist/cli.js"},"_npmUser":{"name":"rowanzhu","email":"rowanzhu@gmail.com"},"repository":{"url":"git+https://github.com/dogsvr/cfg-luban.git","type":"git","directory":"cfg-luban-cli"},"_npmVersion":"11.6.2","description":"Codegen CLI for @dogsvr/cfg-luban (Excel -> LMDB).","directories":{},"_nodeVersion":"24.13.0","dependencies":{"lmdb":"^3.5.4"},"_hasShrinkwrap":false,"devDependencies":{"typescript":"^6.0.3","@types/node":"^24.12.2"},"_npmOperationalInternal":{"tmp":"tmp/cfg-luban-cli_0.4.0_1777812326196_0.3920020336478933","host":"s3://npm-registry-packages-npm-production"}},"0.4.1":{"name":"@dogsvr/cfg-luban-cli","version":"0.4.1","description":"Codegen CLI for @dogsvr/cfg-luban (Excel -> LMDB).","keywords":["dogsvr","game-config","luban","flatbuffers","lmdb","codegen","cli"],"bin":{"cfg-luban-cli":"dist/cli.js"},"main":"./dist/pipeline.js","types":"./dist/pipeline.d.ts","exports":{".":{"types":"./dist/pipeline.d.ts","default":"./dist/pipeline.js"},"./package.json":"./package.json"},"scripts":{"build":"rm -rf dist && tsc && chmod +x dist/cli.js"},"repository":{"type":"git","url":"git+https://github.com/dogsvr/cfg-luban.git","directory":"cfg-luban-cli"},"author":{"name":"rowanzhu"},"license":"MIT","bugs":{"url":"https://github.com/dogsvr/cfg-luban/issues"},"homepage":"https://github.com/dogsvr/cfg-luban#readme","dependencies":{"lmdb":"^3.5.4"},"devDependencies":{"@types/node":"^24.12.2","typescript":"^6.0.3"},"gitHead":"b9a6c4c783553f463f6fa52833e56978356f0c90","_id":"@dogsvr/cfg-luban-cli@0.4.1","_nodeVersion":"24.13.0","_npmVersion":"11.6.2","dist":{"integrity":"sha512-AdmsmktV4ZQWZoVpWMSEaJLlIuEWNa0t+gbz0HOHWiFiT8hHMZ9l3M3vmhx3hhpoRpwPr6oSWAWWqJgCAOxMTg==","shasum":"4a1b79fac43b734986a691544a1d8ccc7e3ba0a6","tarball":"https://registry.npmjs.org/@dogsvr/cfg-luban-cli/-/cfg-luban-cli-0.4.1.tgz","fileCount":18,"unpackedSize":50479,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIFZZYfY6+SI0PSRjy1fKqmcl7uDqV4Ue+2lQ2TxuyDEWAiEA/kATGs9IuGwOABUNhSm12Fzwod1ybnHDg2piuq9wgaU="}]},"_npmUser":{"name":"rowanzhu","email":"rowanzhu@gmail.com"},"directories":{},"maintainers":[{"name":"rowanzhu","email":"rowanzhu@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/cfg-luban-cli_0.4.1_1785066339354_0.319467501504735"},"_hasShrinkwrap":false}},"time":{"created":"2026-05-03T12:45:26.062Z","modified":"2026-07-26T11:45:39.638Z","0.4.0":"2026-05-03T12:45:26.337Z","0.4.1":"2026-07-26T11:45:39.481Z"},"bugs":{"url":"https://github.com/dogsvr/cfg-luban/issues"},"author":{"name":"rowanzhu"},"license":"MIT","homepage":"https://github.com/dogsvr/cfg-luban#readme","keywords":["dogsvr","game-config","luban","flatbuffers","lmdb","codegen","cli"],"repository":{"type":"git","url":"git+https://github.com/dogsvr/cfg-luban.git","directory":"cfg-luban-cli"},"description":"Codegen CLI for @dogsvr/cfg-luban (Excel -> LMDB).","maintainers":[{"name":"rowanzhu","email":"rowanzhu@gmail.com"}],"readme":"# @dogsvr/cfg-luban-cli\n\nCodegen CLI for [`@dogsvr/cfg-luban`](../cfg-luban/README.md): compiles designer Excel sheets into a read-only LMDB config database via Luban + FlatBuffers.\n\nFor this repo's overall layout, see the [repo README](../README.md). For how this fits into the wider framework, see [`@dogsvr/dogsvr`](https://github.com/dogsvr/dogsvr); for a working consumer, see [`example-proj-cfg`](../../example-proj-cfg).\n\n## Install\n\n```sh\nnpm install --save-dev @dogsvr/cfg-luban-cli\n```\n\n## Prerequisites\n\nThe CLI orchestrates external tools rather than vendoring them — you supply paths to `Luban.dll` and `flatc` on every invocation via `--luban-dll` / `--flatc` flags (or `LUBAN_DLL` / `FLATC` env vars). Keeping these as caller-supplied paths means:\n\n- Same CLI works across dev machines, CI, container images — each environment points at whatever location its tools live in\n- No vendored native binaries in `node_modules`\n- Tool version bumps are a flag change, not a CLI release\n\nRequired tools:\n\n| Tool | Notes |\n|---|---|\n| **Luban** (`Luban.dll`) | Managed by `dotnet` — cross-platform, works anywhere you have `dotnet` runtime. [Releases](https://github.com/focus-creative-games/luban/releases) |\n| **flatc** (≥ 23.x) | Native binary — OS/arch specific. `flatc.exe` on Windows, Mach-O on macOS, ELF on Linux. [Releases](https://github.com/google/flatbuffers/releases) |\n| **dotnet runtime** | For running Luban.dll. `apt install dotnet-runtime-8.0` / `brew install dotnet` / etc. |\n| **python3 + openpyxl** | Used by `extract-keys` to read `__tables__.xlsx`. `pip install openpyxl` |\n| **Node.js** | Tested on **v24.13.0 on Linux (x86-64)**; other maintained LTS lines are expected to work but are not routinely exercised. File an issue if something breaks on your runtime. |\n\n## Usage\n\n### Full pipeline\n\n```sh\nnpx cfg-luban-cli build \\\n  --luban-dll /opt/luban/Luban.dll \\\n  --flatc     /opt/flatc \\\n  --designer  ./designer_cfg \\\n  --output    ./generated \\\n  --target    all           # optional, defaults to \"all\"\n```\n\nProduces under `--output`:\n\n```\ngenerated/\n├── fbs/             # .fbs schema\n├── json/            # JSON data (sorted by primary keys)\n├── bin/             # per-table FlatBuffers binaries\n├── ts/              # TypeScript accessors (emitted by flatc)\n├── table_keys.json  # primary-key metadata per table\n└── db/              # LMDB (data.mdb + lock.mdb)\n```\n\nThe runtime ([`@dogsvr/cfg-luban`](../cfg-luban/README.md)) consumes `db/` and `table_keys.json` at process start, and the TypeScript accessors under `ts/` when registering each table.\n\n### Single steps\n\nUseful for CI debugging or partial re-runs:\n\n```sh\nnpx cfg-luban-cli extract-keys \\\n  --tables-xlsx ./designer_cfg/Datas/__tables__.xlsx \\\n  --out         ./generated/table_keys.json\n\nnpx cfg-luban-cli sort-json \\\n  --keys     ./generated/table_keys.json \\\n  --json-dir ./generated/json\n\nnpx cfg-luban-cli import-lmdb \\\n  --bin-dir ./generated/bin \\\n  --db-dir  ./generated/db\n```\n\n### Pipeline stages\n\n| Stage | Tool | Input → Output |\n|---|---|---|\n| 1. `run-luban` | `dotnet Luban.dll` | `designer_cfg/*.xlsx` → `fbs/schema.fbs` + `json/*.json` |\n| 1.5. `extract-keys` | `python3` + `openpyxl` | `__tables__.xlsx` → `table_keys.json` |\n| 2. `sort-json` | — | `json/*.json` sorted in place by primary key (required for binary-search lookup at runtime) |\n| 3. `run-flatc` | `flatc` | `schema.fbs` + sorted JSON → `bin/*.bin` + `ts/` |\n| 4. `import-lmdb` | `lmdb` | `bin/*.bin` → `db/data.mdb` |\n\n### Environment variable fallback\n\nWhen a required flag is missing, the CLI falls back to these env vars: `LUBAN_DLL`, `FLATC`, `DESIGNER_DIR`, `OUTPUT_DIR`. CLI flags always win.\n\n## Bundled `templates/`\n\nThe package ships a `templates/` directory (whitelisted via `files` in `package.json`):\n\n```\n@dogsvr/cfg-luban-cli/\n└── templates/\n    └── flatbuffers/\n        └── schema.sbn\n```\n\n`schema.sbn` is a [Scriban](https://github.com/scriban/scriban) template consumed by Luban as a **custom code template** (passed via `--customTemplateDir`). `--customTemplateDir` has **replace** semantics, not merge — when we supply a `flatbuffers/schema.sbn`, it wholesale replaces Luban's stock template. Most of our file therefore just reproduces the stock behavior; the two lines that actually differ from stock are:\n\n- **No per-table `root_type`**. FlatBuffers only honors the *last* `root_type` in a schema — multiple tables would silently shadow each other. Luban's stock template emits one, so our replacement omits it. Instead, `run-flatc` passes `--root-type cfg.Tb<X>` to `flatc` on every per-table binary compile.\n- **Single `file_identifier \"CFGL\"`** stamped into every `.bin`, used only as a sanity magic (per-table uniqueness is enforced by filename + schema, not magic).\n\nEverything else — the `enum` / `union` / `table` / `KeyValue_*` / `Tb<X> { data_list: [<X>] }` sections — is a **faithful reproduction of Luban's native output**. In particular:\n\n- Each table is wrapped as `Tb<X> { data_list: [<X>] }` not because we invented that shape, but because `FlatBuffersJsonExporter` (Luban's JSON emitter) **hardcodes** the field name `data_list`. Luban's JSON output for every table is `{ \"data_list\": [...] }`. If our `.fbs` didn't declare a matching `Tb<X>.data_list`, flatc would fail to compile the JSON.\n- We have to keep this section in the custom template purely because of the replace semantics — omit it, and the wrapping disappears from `.fbs` while Luban still emits JSON expecting it.\n\nThe `// WARN! The name 'data_list' is used by FlatBuffersJsonExporter. don't modify it!` comment in the template exists to remind future editors of exactly this constraint.\n\n### How it's wired at runtime\n\n`run-luban` resolves the template dir relative to the installed package root:\n\n```ts\n// src/pipeline.ts\nconst customTemplateDir = path.resolve(__dirname, '..', 'templates');\n// dist/pipeline.js  -> <pkg>/templates   (published layout)\n// src/pipeline.ts   -> <pkg>/templates   (local dev layout)\n```\n\nConsumers **never** configure the template path — it's implementation detail. If you need to change the schema shape, edit `templates/flatbuffers/schema.sbn` in this repo and rebuild, rather than forking at the consumer.\n\n### Adding more templates\n\nTo override additional Luban target templates, add files under `templates/<target>/<name>.sbn`. The whole `templates/` tree is passed as `--customTemplateDir` to Luban, which matches by `<target>/<name>` convention against its stock templates.\n","readmeFilename":"README.md"}