@ifc-lite/cli 0.34.0 → 0.36.1

package/dist/help.js

@@ -0,0 +1,260 @@
+/* This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at https://mozilla.org/MPL/2.0/. */
+/**
+ * The CLI's `--help` text. Split out of `index.ts` (module-size ratchet,
+ * #5138 PR 7b added the `check` command line and pushed `index.ts` over
+ * 400 lines) — pure data, no logic, so it carries no behaviour of its own.
+ */
+export function buildHelp(version) {
+    return `
+  ifc-lite v${version} — BIM toolkit for the terminal
+
+  Usage: ifc-lite <command> [options]
+
+  Commands:
+    info      <file.ifc>                          Model summary (schema, entities, storeys)
+    query     <file.ifc> [--type T] [--json]      Query entities by type/properties/quantities
+              [--select "IfcWall, Pset_WallCommon.FireRating=2HR"]  IfcOpenShell-style selector (classes union with --type; properties AND with --where)
+    props     <file.ifc> --id <N>                 All properties for a single entity
+    export    <file.ifc> --format csv|json|ifc|obj|gltf|glb|jsonld|step|ifcx|usd|hbjson|dfjson  Export data / geometry / energy model
+    schedule  <file.ifc> --type T --columns "H=path,..."  Tabular schedule of one class (csv/json/md/html)
+              [--preset door|window|space|wall|material-takeoff]  default type+columns (flags override)
+              [--where PsetName.Prop=Value] [--format csv|json|md|html]  path = attr | Pset.Prop | Qto.Qty
+              [--sort "Header[:asc|desc],..."]  multi-key row sort by column HEADER (numbers numeric, nulls last)
+              [--group-by "Header,..."]  contiguous groups, ordered by group key (asc, or --sort's dir)
+              [--subtotals "count|sum:H|avg:H|min:H|max:H,..."]  subtotal row per group + grand total
+                 (without --group-by: grand total only; CSV/md label the group column, JSON marks __row)
+              [--spec spec.json]  load a saved schedule definition (beats --preset; an explicit flag beats both)
+              [--save spec.json]  persist this invocation's resolved definition for --spec reuse
+    diagnose-geometry <file.ifc> [--json]        CSG / opening diagnostics (failures, classification)
+                      [--product ID|GUID] [--type T]  Filter worst-hosts detail to one product/type
+    extract-entities <file.ifc> --out F          Isolate entities into a small, viewable standalone IFC
+                      [--product ID|GUID] [--storey S] [--detect] [--view]  by GUID/type/storey or auto-triage
+    anonymize <file.ifc> --out F                 Export selected objects + context as an anonymized IFC
+                      [--id N,...] [--guid G,...] [--type T] [--storey S]
+                      [--keep-psets] [--keep-names] [--keep-other-names] [--keep-currency]
+                      [--no-rel-voids-element] [--no-rel-fills-element] [--no-rel-defines-by-type]
+                      [--no-rel-associates-material] [--no-rel-aggregates] [--no-rel-nests]
+                      [--connect-depth N] [--guid-map F] [--json]
+    ids       <file.ifc> <rules.ids>              Validate against IDS rules
+    bcf       <create|list|add-comment>           Work with BCF collaboration files
+    clash     <file.ifc> [--matrix] [--bcf F]      Detect geometric clashes between elements
+    create    <type> [options] --out F             Create IFC elements (29 types)
+    eval      <file.ifc> "<expression>"           Evaluate SDK expression
+    run       <script.js> <file.ifc>              Execute a script against model
+    schema                                        Dump SDK API schema (for LLM tools)
+    merge     <f1.ifc> <f2.ifc> --out F           Merge multiple IFC files
+    convert   <file.ifc> --schema VER --out F     Convert between IFC schema versions
+    diff      <f1.ifc> <f2.ifc>                   Compare two IFC files
+              [--by-content] [--identity-out F] [--identity-in F]  Match re-GUIDed elements by content; save/replay the identity map
+              [--geometry] [--split-merge] [--successors]  Wasm mesh pass: world geometry hashes/boxes/volumes; split/merge + successor claims
+              [--lineage-out F] [--lineage-in F] [--accept F] [--key-from Tag|Pset.Prop]  Lineage for rekeying external data; authored key
+    rekey     <table.csv|json> --lineage F --out F  Carry a table keyed on old element keys across a revision
+    validate  <file.ifc>                          Structural validation checks
+    bsdd      <class|search|psets|qsets> <arg>     buildingSMART Data Dictionary lookup
+    stats     <file.ifc>                          Auto-calculated model KPIs and health check
+    mutate    <file.ifc> --id N --set P=V --out F  Modify properties/attributes and save
+    generate-spaces <file.ifc> --out F           Derive IfcSpace from walls (slab/roof-aware height)
+    ask       <file.ifc> "<question>"            Natural language BIM queries
+    view      <file.ifc> [--port N]              Interactive 3D viewer in browser
+    analyze   <file.ifc> --viewer <port>        Query + visualize analysis results
+    lod       <file.ifc> --level 0|1            Generate lightweight LOD artifacts
+    simplify  <file.ifc> --out F [--level 1..5] [--ids 1,2,...] [--json]  Demesher: simplify meshes, write lighter IFC
+    mcp       <file.ifc> [--transport stdio|http] Start an MCP server bound to one or more IFC files
+    ext       validate <path>|init <dir>          Manage IFClite extensions (Phase 0 — validate, init)
+    layer     <publish|diff|merge|log|bake|...>    Layered change tracking over a local store (.ifc-lite/)
+    ref       <list|create|move|protect>           Manage named refs in the layer store
+    gym       --model <file.ifc> | --seed <n>      reset/step/reward environment loop (JSONL over stdin/stdout)
+    delivery  <recipe.json> [--json] [--out F] [--html F]  Repeatable delivery check (structural + IDS + rule sets) from a saved recipe
+              recipe: {"models":["m.ifc"],"structural":true,"ids":["rules.ids"],"rules":["checks.rules.json"]}, paths relative to the recipe file
+    check     <model.ifc>... --rules <file.rules.json>     Run a .rules.json information-validation rule set (same engine as the viewer)
+              [--format json|table] [--fail-on error|warning]  exit 0 all pass / 1 any fail / 2 rule error or unreadable input
+    flow      <run|describe|validate> <graph.flow.json> [<file.ifc>] [--input k=v] [--out F]  Evaluate a node graph headlessly
+
+  Options:
+    --help, -h           Show help
+    --version, -v        Show version
+    --json               Output as JSON (machine-readable)
+    --verbose            Show parser + geometry diagnostics (stderr)
+    --quiet              Errors only
+    --debug              Verbose + stack traces on error
+    --log-level <level>  error|warn|info|debug (explicit wins over shorthands)
+
+  Examples:
+    ifc-lite info model.ifc
+    ifc-lite query model.ifc --type IfcWall --json
+    ifc-lite query model.ifc --type IfcDoor --props --limit 5
+    ifc-lite query model.ifc --type IfcWall --materials --classifications --json
+    ifc-lite query model.ifc --type IfcWall --all --json
+    ifc-lite query model.ifc --type IfcWall --quantity-names
+    ifc-lite query model.ifc --type IfcWall --sum GrossSideArea
+    ifc-lite query model.ifc --type IfcWall --group-by material --json
+    ifc-lite query model.ifc --spatial --summary
+    ifc-lite query model.ifc --spatial
+    ifc-lite props model.ifc --id 42
+    ifc-lite export model.ifc --format csv --type IfcWall --columns Name,Type,GlobalId
+    ifc-lite export model.ifc --format json --type IfcWall,IfcDoor
+    ifc-lite schedule model.ifc --type IfcDoor --columns "Name=Name, Mark=Pset_DoorCommon.Reference"
+    ifc-lite schedule model.ifc --type IfcWall --columns "Name,Qto_WallBaseQuantities.NetVolume" --where Pset_WallCommon.IsExternal=true --format json
+    ifc-lite schedule model.ifc --type IfcDoor --columns "Name=Name, Fire=Pset_DoorCommon.FireRating, Area=Qto_DoorBaseQuantities.Area" --group-by Fire --sort "Area:desc" --subtotals "count, sum:Area"
+    ifc-lite schedule model.ifc --preset door
+    ifc-lite schedule model.ifc --preset material-takeoff --format json
+    ifc-lite schedule model.ifc --preset door --format md
+    ifc-lite schedule model.ifc --preset door --format html > doors.html
+    ifc-lite schedule model.ifc --preset door --save door-schedule.json
+    ifc-lite schedule model.ifc --spec door-schedule.json --format json
+    ifc-lite diagnose-geometry model.ifc --json
+    ifc-lite diagnose-geometry model.ifc --type IfcWall
+    ifc-lite diagnose-geometry model.ifc --product 0YvCT2_$X3_xJG3rzD8L_8
+    ifc-lite ids model.ifc requirements.ids --json
+    ifc-lite bcf create --title "Missing door" --out topic.bcf
+    ifc-lite clash model.ifc --matrix --json
+    ifc-lite clash model.ifc --a "IfcDuct*|IfcPipe*" --b "IfcWall*" --mode clearance --clearance 0.05
+    ifc-lite clash model.ifc --matrix --bcf clashes.bcfzip
+    ifc-lite create wall --height 3 --thickness 0.2 --start 0,0,0 --end 5,0,0 --out wall.ifc
+    ifc-lite create stair --number-of-risers 12 --riser-height 0.175 --width 1.2 --out stair.ifc
+    ifc-lite create door --width 0.9 --height 2.1 --position 0,0,0 --out door.ifc
+    ifc-lite create i-shape-beam --start 0,0,3 --end 5,0,3 --out beam.ifc
+    ifc-lite create wall --from-json --out w.ifc < params.json
+    ifc-lite create wall --pset '{"Name":"Pset_WallCommon","Properties":[{"Name":"IsExternal","NominalValue":true}]}' --out w.ifc
+    ifc-lite create wall --material '{"Name":"Concrete","Category":"Structural"}' --out w.ifc
+    ifc-lite create wall --color 0.8,0.2,0.2 --out w.ifc
+    ifc-lite eval model.ifc "bim.query().byType('IfcWall').count()"
+    ifc-lite eval model.ifc "bim.storeys().map(s => s.name)"
+    ifc-lite run analysis.js model.ifc
+    ifc-lite schema
+    ifc-lite schema --compact
+    ifc-lite merge arch.ifc struct.ifc mep.ifc --out federated.ifc
+    ifc-lite convert model.ifc --schema IFC4 --out model-ifc4.ifc
+    ifc-lite diff model-v1.ifc model-v2.ifc --json
+    ifc-lite diff model-v1.ifc model-v2.ifc --by-entity
+    ifc-lite diff model-v1.ifc model-v2.ifc --by-content --identity-out renames.json
+    ifc-lite diff model-v1.ifc model-v2.ifc --identity-in renames.json
+    ifc-lite diff model-v1.ifc model-v2.ifc --geometry --split-merge --successors --json
+    ifc-lite diff model-v1.ifc model-v2.ifc --key-from Pset_Asset.AssetId --lineage-out lineage.json
+    ifc-lite rekey costs.csv --lineage lineage.json --key-column GlobalId --out costs-v2.csv
+    ifc-lite validate model.ifc --json
+    ifc-lite bsdd class IfcWall
+    ifc-lite bsdd search "concrete wall"
+    ifc-lite bsdd psets IfcWall
+    ifc-lite ask model.ifc "how many walls?"
+    ifc-lite ask model.ifc "window-wall ratio" --json
+    ifc-lite ask model.ifc "list materials" --explain
+    ifc-lite view model.ifc
+    ifc-lite view model.ifc --port 3456
+    curl -X POST http://localhost:3456/api/command -H 'Content-Type: application/json' -d '{"action":"colorize","type":"IfcWall","color":[1,0,0,1]}'
+    ifc-lite analyze model.ifc --viewer 3456 --type IfcWall --missing "Pset_WallCommon.FireRating" --color red
+    ifc-lite analyze model.ifc --viewer 3456 --type IfcSlab --where "GrossArea>100" --color orange --isolate
+    ifc-lite analyze model.ifc --viewer 3456 --type IfcWall --heatmap "Qto_WallBaseQuantities.GrossSideArea"
+    ifc-lite analyze model.ifc --viewer 3456 --rules rules.json --json
+    ifc-lite lod model.ifc --level 0 --out model.lod0.json
+    ifc-lite lod model.ifc --level 1 --out model.glb --meta model.lod1.json
+    ifc-lite mcp model.ifc
+    ifc-lite mcp model.ifc --read-only
+    ifc-lite mcp arch.ifc struct.ifc --federate
+    ifc-lite mcp model.ifc --transport http --port 8765 --token abc
+    ifc-lite ref create main
+    ifc-lite layer publish delta.ifcx --base main --intent "Set fire ratings" --scope "model.mutate:Pset_FireSafety*@IfcWall"
+    ifc-lite layer merge blake3:abc123 --into main --preview
+    ifc-lite layer log main
+    ifc-lite layer bake main -o flat.ifcx
+    ifc-lite gym --model model.ifc --checks schema,clash
+    ifc-lite gym --model model.ifc --checks schema,clash,ids --ids rules.ids
+    ifc-lite gym --seed 42 --checks schema,clash
+
+  Pipe-friendly:
+    ifc-lite query model.ifc --type IfcWall --json | jq '.[].name'
+    ifc-lite export model.ifc --format csv --type IfcSlab > slabs.csv
+    echo '{"Start":[0,0,0],"End":[10,0,0],"Height":3}' | ifc-lite create wall --from-json --out w.ifc
+
+  Create element types:
+    wall, slab, column, beam, stair, roof, gable-roof, door, window,
+    wall-door, wall-window, ramp, railing, plate, member, footing, pile,
+    space, curtain-wall, furnishing, proxy, circular-column,
+    hollow-circular-column, i-shape-beam, l-shape-member, t-shape-member,
+    u-shape-member, rectangle-hollow-beam
+
+  gym protocol (newline-delimited JSON, one command per stdin line):
+    On start:            {"type":"reset","observation":{entityCounts,storeyCount,schema,bounds},"channels":{...}}
+    -> {"type":"step","ops":[{"op":"setProperty"|"setAttribute"|"deleteProperty", ...}]}
+    <- {"type":"reward","channels":{schema:{score,...},clash:{score,...},ids:{score,...}},"done":false}
+    -> {"type":"reset"}               reloads the pristine model, replies like the initial reset
+    -> {"type":"reset","seed":8}      episode factory: swaps to a generated World Gym benchmark
+                                      model (optional "family"/"corrupt"/"corruptRate" fields);
+                                      needs the repo checkout (tools/world-gym). Also on start via
+                                      --seed <n> [--family ...] [--corrupt|--no-corrupt|--corrupt-rate p].
+                                      Generated-episode resets add "episode":{seed,family,corrupted}.
+    -> {"type":"close"}               exits 0
+    Malformed input replies {"type":"error","message":"..."} instead of crashing.
+    v0 ops: setProperty/setAttribute/deleteProperty only (mirrors bim.mutate's method
+    names). Geometry-creating ops are out of scope for v0.
+
+  Learn more: https://ifclite.com
+`;
+}
+/**
+ * The `Commands:` block, as a map from command name to its rows (the command's
+ * own line plus any deeper-indented continuation lines).
+ *
+ * Derived from the same literal `buildHelp` returns rather than a second
+ * hand-written table: `scripts/docs/generate-docs-sections.mjs` already parses
+ * that block for the docs table, so a per-command help built any other way
+ * would be a third place to forget when a flag changes.
+ *
+ * A command row starts at exactly four spaces then the name; continuation rows
+ * are indented deeper. Long names (`diagnose-geometry`, `extract-entities`)
+ * leave only ONE space before their `<args>`, so the gap is `\s+`, not `\s{2,}`.
+ */
+function parseCommandBlock(help) {
+    const block = help.match(/\n {2}Commands:\n([\s\S]*?)\n {2}Options:/);
+    const commands = new Map();
+    if (!block)
+        return commands;
+    let current;
+    for (const line of block[1].split('\n')) {
+        const head = line.match(/^ {4}([a-z][\w-]*)\s+\S/);
+        if (head) {
+            current = [line];
+            commands.set(head[1], current);
+        }
+        else if (current && /^ {6,}\S/.test(line)) {
+            current.push(line);
+        }
+        else if (line.trim() === '') {
+            current = undefined;
+        }
+    }
+    return commands;
+}
+/** Every command name the help text documents. */
+export function helpCommandNames(version = '0.0.0') {
+    return [...parseCommandBlock(buildHelp(version)).keys()];
+}
+/**
+ * Help for ONE command.
+ *
+ * `ifc-lite <command> --help` used to print the global help for all 37
+ * commands, because `index.ts` tested `args.includes('--help')` before
+ * dispatch and `args` still held the command name (#5527). The CLI's own docs
+ * tell LLM users to "discover all capabilities by running `ifc-lite --help`";
+ * there was no second level to discover.
+ *
+ * Returns `null` for a name the help text does not document, so the caller can
+ * fall back to the global help rather than print an empty section.
+ */
+export function buildCommandHelp(version, command) {
+    const rows = parseCommandBlock(buildHelp(version)).get(command);
+    if (!rows)
+        return null;
+    return [
+        ``,
+        `  ifc-lite ${command} — see \`ifc-lite --help\` for every command`,
+        ``,
+        ...rows,
+        ``,
+        `  Full reference: https://ifclite.dev/docs/guide/cli/`,
+        ``,
+    ].join('\n');
+}
+//# sourceMappingURL=help.js.map

package/dist/help.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"help.js","sourceRoot":"","sources":["../src/help.ts"],"names":[],"mappings":"AAAA;;+DAE+D;AAE/D;;;;GAIG;AAEH,MAAM,UAAU,SAAS,CAAC,OAAe;IACvC,OAAO;cACK,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAuLpB,CAAC;AACF,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,SAAS,iBAAiB,CAAC,IAAY;IACrC,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,2CAA2C,CAAC,CAAC;IACtE,MAAM,QAAQ,GAAG,IAAI,GAAG,EAAoB,CAAC;IAC7C,IAAI,CAAC,KAAK;QAAE,OAAO,QAAQ,CAAC;IAE5B,IAAI,OAA6B,CAAC;IAClC,KAAK,MAAM,IAAI,IAAI,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;QACxC,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,yBAAyB,CAAC,CAAC;QACnD,IAAI,IAAI,EAAE,CAAC;YACT,OAAO,GAAG,CAAC,IAAI,CAAC,CAAC;YACjB,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC;QACjC,CAAC;aAAM,IAAI,OAAO,IAAI,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;YAC5C,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACrB,CAAC;aAAM,IAAI,IAAI,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC;YAC9B,OAAO,GAAG,SAAS,CAAC;QACtB,CAAC;IACH,CAAC;IACD,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED,kDAAkD;AAClD,MAAM,UAAU,gBAAgB,CAAC,OAAO,GAAG,OAAO;IAChD,OAAO,CAAC,GAAG,iBAAiB,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC;AAC3D,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,gBAAgB,CAAC,OAAe,EAAE,OAAe;IAC/D,MAAM,IAAI,GAAG,iBAAiB,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;IAChE,IAAI,CAAC,IAAI;QAAE,OAAO,IAAI,CAAC;IACvB,OAAO;QACL,EAAE;QACF,cAAc,OAAO,8CAA8C;QACnE,EAAE;QACF,GAAG,IAAI;QACP,EAAE;QACF,uDAAuD;QACvD,EAAE;KACH,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACf,CAAC"}

package/dist/index.js

@@ -9,6 +9,8 @@
  * from the command line. Designed for both humans and LLM terminals.
  */
 import { logger, parseVerbosity } from './logger.js';
+import { fatal } from './output.js';
+import { COMMANDS_WITH_OUT } from './out-flag-commands.js';
 import { infoCommand } from './commands/info.js';
 import { queryCommand } from './commands/query.js';
 import { scheduleCommand } from './commands/schedule.js';
@@ -44,197 +46,21 @@ import { layerCommand } from './commands/layer.js';
 import { refCommand } from './commands/ref.js';
 import { gymCommand } from './commands/gym.js';
 import { deliveryCommand } from './commands/delivery.js';
+import { checkCommand } from './commands/check.js';
+import { flowCommand } from './commands/flow.js';
 import { fileURLToPath } from 'node:url';
 import { dirname, join } from 'node:path';
-import { readCliVersion } from './version.js';
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = dirname(__filename);
+import { readPackageVersion } from '@ifc-lite/data';
+import { buildHelp, buildCommandHelp } from './help.js';
 // package.json sits one level above both `src/` and `dist/`.
-const VERSION = readCliVersion(join(__dirname, '..', 'package.json'));
-const HELP = `
-  ifc-lite v${VERSION} — BIM toolkit for the terminal
-
-  Usage: ifc-lite <command> [options]
-
-  Commands:
-    info      <file.ifc>                          Model summary (schema, entities, storeys)
-    query     <file.ifc> [--type T] [--json]      Query entities by type/properties/quantities
-              [--select "IfcWall, Pset_WallCommon.FireRating=2HR"]  IfcOpenShell-style selector (classes union with --type; properties AND with --where)
-    props     <file.ifc> --id <N>                 All properties for a single entity
-    export    <file.ifc> --format csv|json|ifc|obj|gltf|glb|jsonld|step|ifcx|usd|hbjson|dfjson  Export data / geometry / energy model
-    schedule  <file.ifc> --type T --columns "H=path,..."  Tabular schedule of one class (csv/json/md/html)
-              [--preset door|window|space|wall|material-takeoff]  default type+columns (flags override)
-              [--where PsetName.Prop=Value] [--format csv|json|md|html]  path = attr | Pset.Prop | Qto.Qty
-              [--sort "Header[:asc|desc],..."]  multi-key row sort by column HEADER (numbers numeric, nulls last)
-              [--group-by "Header,..."]  contiguous groups, ordered by group key (asc, or --sort's dir)
-              [--subtotals "count|sum:H|avg:H|min:H|max:H,..."]  subtotal row per group + grand total
-                 (without --group-by: grand total only; CSV/md label the group column, JSON marks __row)
-              [--spec spec.json]  load a saved schedule definition (beats --preset; an explicit flag beats both)
-              [--save spec.json]  persist this invocation's resolved definition for --spec reuse
-    diagnose-geometry <file.ifc> [--json]        CSG / opening diagnostics (failures, classification)
-                      [--product ID|GUID] [--type T]  Filter worst-hosts detail to one product/type
-    extract-entities <file.ifc> --out F          Isolate entities into a small, viewable standalone IFC
-                      [--product ID|GUID] [--storey S] [--detect] [--view]  by GUID/type/storey or auto-triage
-    anonymize <file.ifc> --out F                 Export selected objects + context as an anonymized IFC
-                      [--id N,...] [--guid G,...] [--type T] [--storey S]
-                      [--keep-psets] [--keep-names] [--keep-other-names] [--keep-currency]
-                      [--no-rel-voids-element] [--no-rel-fills-element] [--no-rel-defines-by-type]
-                      [--no-rel-associates-material] [--no-rel-aggregates] [--no-rel-nests]
-                      [--connect-depth N] [--guid-map F] [--json]
-    ids       <file.ifc> <rules.ids>              Validate against IDS rules
-    bcf       <create|list|add-comment>           Work with BCF collaboration files
-    clash     <file.ifc> [--matrix] [--bcf F]      Detect geometric clashes between elements
-    create    <type> [options] --out F             Create IFC elements (30+ types)
-    eval      <file.ifc> "<expression>"           Evaluate SDK expression
-    run       <script.js> <file.ifc>              Execute a script against model
-    schema                                        Dump SDK API schema (for LLM tools)
-    merge     <f1.ifc> <f2.ifc> --out F           Merge multiple IFC files
-    convert   <file.ifc> --schema VER --out F     Convert between IFC schema versions
-    diff      <f1.ifc> <f2.ifc>                   Compare two IFC files
-              [--by-content] [--identity-out F] [--identity-in F]  Match re-GUIDed elements by content; save/replay the identity map
-              [--geometry] [--split-merge] [--successors]  Wasm mesh pass: world geometry hashes/boxes/volumes; split/merge + successor claims
-              [--lineage-out F] [--lineage-in F] [--accept F] [--key-from Tag|Pset.Prop]  Lineage for rekeying external data; authored key
-    rekey     <table.csv|json> --lineage F --out F  Carry a table keyed on old element keys across a revision
-    validate  <file.ifc>                          Structural validation checks
-    bsdd      <class|search|psets|qsets> <arg>     buildingSMART Data Dictionary lookup
-    stats     <file.ifc>                          Auto-calculated model KPIs and health check
-    mutate    <file.ifc> --id N --set P=V --out F  Modify properties/attributes and save
-    generate-spaces <file.ifc> --out F           Derive IfcSpace from walls (slab/roof-aware height)
-    ask       <file.ifc> "<question>"            Natural language BIM queries
-    view      <file.ifc> [--port N]              Interactive 3D viewer in browser
-    analyze   <file.ifc> --viewer <port>        Query + visualize analysis results
-    lod       <file.ifc> --level 0|1            Generate lightweight LOD artifacts
-    simplify  <file.ifc> --out F [--level 1..5] [--ids 1,2,...] [--json]  Demesher: simplify meshes, write lighter IFC
-    mcp       <file.ifc> [--transport stdio|http] Start an MCP server bound to one or more IFC files
-    ext       validate <path>|init <dir>          Manage IFClite extensions (Phase 0 — validate, init)
-    layer     <publish|diff|merge|log|bake|...>    Layered change tracking over a local store (.ifc-lite/)
-    ref       <list|create|move|protect>           Manage named refs in the layer store
-    gym       --model <file.ifc> | --seed <n>      reset/step/reward environment loop (JSONL over stdin/stdout)
-    delivery  <recipe.json> [--json] [--out F] [--html F]  Repeatable delivery check (structural + IDS) from a saved recipe
-              recipe: {"models":["m.ifc"],"structural":true,"ids":["rules.ids"]}, paths relative to the recipe file
-
-  Options:
-    --help, -h           Show help
-    --version, -v        Show version
-    --json               Output as JSON (machine-readable)
-    --out <file>         Write output to file instead of stdout
-    --verbose            Show parser + geometry diagnostics (stderr)
-    --quiet              Errors only
-    --debug              Verbose + stack traces on error
-    --log-level <level>  error|warn|info|debug (explicit wins over shorthands)
-
-  Examples:
-    ifc-lite info model.ifc
-    ifc-lite query model.ifc --type IfcWall --json
-    ifc-lite query model.ifc --type IfcDoor --props --limit 5
-    ifc-lite query model.ifc --type IfcWall --materials --classifications --json
-    ifc-lite query model.ifc --type IfcWall --all --json
-    ifc-lite query model.ifc --type IfcWall --quantity-names
-    ifc-lite query model.ifc --type IfcWall --sum GrossSideArea
-    ifc-lite query model.ifc --type IfcWall --group-by material --json
-    ifc-lite query model.ifc --spatial --summary
-    ifc-lite query model.ifc --spatial
-    ifc-lite props model.ifc --id 42
-    ifc-lite export model.ifc --format csv --type IfcWall --columns Name,Type,GlobalId
-    ifc-lite export model.ifc --format json --type IfcWall,IfcDoor
-    ifc-lite schedule model.ifc --type IfcDoor --columns "Name=Name, Mark=Pset_DoorCommon.Reference"
-    ifc-lite schedule model.ifc --type IfcWall --columns "Name,Qto_WallBaseQuantities.NetVolume" --where Pset_WallCommon.IsExternal=true --format json
-    ifc-lite schedule model.ifc --type IfcDoor --columns "Name=Name, Fire=Pset_DoorCommon.FireRating, Area=Qto_DoorBaseQuantities.Area" --group-by Fire --sort "Area:desc" --subtotals "count, sum:Area"
-    ifc-lite schedule model.ifc --preset door
-    ifc-lite schedule model.ifc --preset material-takeoff --format json
-    ifc-lite schedule model.ifc --preset door --format md
-    ifc-lite schedule model.ifc --preset door --format html > doors.html
-    ifc-lite schedule model.ifc --preset door --save door-schedule.json
-    ifc-lite schedule model.ifc --spec door-schedule.json --format json
-    ifc-lite diagnose-geometry model.ifc --json
-    ifc-lite diagnose-geometry model.ifc --type IfcWall
-    ifc-lite diagnose-geometry model.ifc --product 0YvCT2_$X3_xJG3rzD8L_8
-    ifc-lite ids model.ifc requirements.ids --json
-    ifc-lite bcf create --title "Missing door" --out topic.bcf
-    ifc-lite clash model.ifc --matrix --json
-    ifc-lite clash model.ifc --a "IfcDuct*|IfcPipe*" --b "IfcWall*" --mode clearance --clearance 0.05
-    ifc-lite clash model.ifc --matrix --bcf clashes.bcfzip
-    ifc-lite create wall --height 3 --thickness 0.2 --start 0,0,0 --end 5,0,0 --out wall.ifc
-    ifc-lite create stair --number-of-risers 12 --riser-height 0.175 --width 1.2 --out stair.ifc
-    ifc-lite create door --width 0.9 --height 2.1 --position 0,0,0 --out door.ifc
-    ifc-lite create i-shape-beam --start 0,0,3 --end 5,0,3 --out beam.ifc
-    ifc-lite create wall --from-json --out w.ifc < params.json
-    ifc-lite create wall --pset '{"Name":"Pset_WallCommon","Properties":[{"Name":"IsExternal","NominalValue":true}]}' --out w.ifc
-    ifc-lite create wall --material '{"Name":"Concrete","Category":"Structural"}' --out w.ifc
-    ifc-lite create wall --color 0.8,0.2,0.2 --out w.ifc
-    ifc-lite eval model.ifc "bim.query().byType('IfcWall').count()"
-    ifc-lite eval model.ifc "bim.storeys().map(s => s.name)"
-    ifc-lite run analysis.js model.ifc
-    ifc-lite schema
-    ifc-lite schema --compact
-    ifc-lite merge arch.ifc struct.ifc mep.ifc --out federated.ifc
-    ifc-lite convert model.ifc --schema IFC4 --out model-ifc4.ifc
-    ifc-lite diff model-v1.ifc model-v2.ifc --json
-    ifc-lite diff model-v1.ifc model-v2.ifc --by-entity
-    ifc-lite diff model-v1.ifc model-v2.ifc --by-content --identity-out renames.json
-    ifc-lite diff model-v1.ifc model-v2.ifc --identity-in renames.json
-    ifc-lite diff model-v1.ifc model-v2.ifc --geometry --split-merge --successors --json
-    ifc-lite diff model-v1.ifc model-v2.ifc --key-from Pset_Asset.AssetId --lineage-out lineage.json
-    ifc-lite rekey costs.csv --lineage lineage.json --key-column GlobalId --out costs-v2.csv
-    ifc-lite validate model.ifc --json
-    ifc-lite bsdd class IfcWall
-    ifc-lite bsdd search "concrete wall"
-    ifc-lite bsdd psets IfcWall
-    ifc-lite ask model.ifc "how many walls?"
-    ifc-lite ask model.ifc "window-wall ratio" --json
-    ifc-lite ask model.ifc "list materials" --explain
-    ifc-lite view model.ifc
-    ifc-lite view model.ifc --port 3456
-    curl -X POST http://localhost:3456/api/command -H 'Content-Type: application/json' -d '{"action":"colorize","type":"IfcWall","color":[1,0,0,1]}'
-    ifc-lite analyze model.ifc --viewer 3456 --type IfcWall --missing "Pset_WallCommon.FireRating" --color red
-    ifc-lite analyze model.ifc --viewer 3456 --type IfcSlab --where "GrossArea>100" --color orange --isolate
-    ifc-lite analyze model.ifc --viewer 3456 --type IfcWall --heatmap "Qto_WallBaseQuantities.GrossSideArea"
-    ifc-lite analyze model.ifc --viewer 3456 --rules rules.json --json
-    ifc-lite lod model.ifc --level 0 --out model.lod0.json
-    ifc-lite lod model.ifc --level 1 --out model.glb --meta model.lod1.json
-    ifc-lite mcp model.ifc
-    ifc-lite mcp model.ifc --read-only
-    ifc-lite mcp arch.ifc struct.ifc --federate
-    ifc-lite mcp model.ifc --transport http --port 8765 --token abc
-    ifc-lite ref create main
-    ifc-lite layer publish delta.ifcx --base main --intent "Set fire ratings" --scope "model.mutate:Pset_FireSafety*@IfcWall"
-    ifc-lite layer merge blake3:abc123 --into main --preview
-    ifc-lite layer log main
-    ifc-lite layer bake main -o flat.ifcx
-    ifc-lite gym --model model.ifc --checks schema,clash
-    ifc-lite gym --model model.ifc --checks schema,clash,ids --ids rules.ids
-    ifc-lite gym --seed 42 --checks schema,clash
-
-  Pipe-friendly:
-    ifc-lite query model.ifc --type IfcWall --json | jq '.[].name'
-    ifc-lite export model.ifc --format csv --type IfcSlab > slabs.csv
-    echo '{"Start":[0,0,0],"End":[10,0,0],"Height":3}' | ifc-lite create wall --from-json --out w.ifc
-
-  Create element types:
-    wall, slab, column, beam, stair, roof, gable-roof, door, window,
-    wall-door, wall-window, ramp, railing, plate, member, footing, pile,
-    space, curtain-wall, furnishing, proxy, circular-column,
-    hollow-circular-column, i-shape-beam, l-shape-member, t-shape-member,
-    u-shape-member, rectangle-hollow-beam
-
-  gym protocol (newline-delimited JSON, one command per stdin line):
-    On start:            {"type":"reset","observation":{entityCounts,storeyCount,schema,bounds},"channels":{...}}
-    -> {"type":"step","ops":[{"op":"setProperty"|"setAttribute"|"deleteProperty", ...}]}
-    <- {"type":"reward","channels":{schema:{score,...},clash:{score,...},ids:{score,...}},"done":false}
-    -> {"type":"reset"}               reloads the pristine model, replies like the initial reset
-    -> {"type":"reset","seed":8}      episode factory: swaps to a generated World Gym benchmark
-                                      model (optional "family"/"corrupt"/"corruptRate" fields);
-                                      needs the repo checkout (tools/world-gym). Also on start via
-                                      --seed <n> [--family ...] [--corrupt|--no-corrupt|--corrupt-rate p].
-                                      Generated-episode resets add "episode":{seed,family,corrupted}.
-    -> {"type":"close"}               exits 0
-    Malformed input replies {"type":"error","message":"..."} instead of crashing.
-    v0 ops: setProperty/setAttribute/deleteProperty only (mirrors bim.mutate's method
-    names). Geometry-creating ops are out of scope for v0.
-
-  Learn more: https://ifclite.com
-`;
+const VERSION = readPackageVersion(join(dirname(fileURLToPath(import.meta.url)), '..', 'package.json'));
 /** Command being executed, captured for the top-level error handler. */
+/**
+ * Commands that handle `--help` themselves, with more detail than the global
+ * `Commands:` block carries. Their handlers already tested for it; before
+ * #5527 that branch was simply unreachable.
+ */
+const HELP_DELEGATING_COMMANDS = new Set(['layer', 'ref', 'ext']);
 let activeCommand = '';
 /** True when --debug was passed (stack traces on error). */
 let debugFlag = false;
@@ -245,10 +71,25 @@ async function main() {
     logger.configure({ level: verbosity.level });
     debugFlag = verbosity.debug;
     const args = verbosity.rest;
-    if (args.length === 0 || args.includes('--help') || args.includes('-h')) {
-        process.stdout.write(HELP + '\n');
+    const wantsHelp = args.includes('--help') || args.includes('-h');
+    if (args.length === 0) {
+        process.stdout.write(buildHelp(VERSION) + '\n');
         return;
     }
+    if (wantsHelp) {
+        // `--help` used to be answered globally BEFORE dispatch, with the command
+        // still sitting in `args`, so all 37 subcommands printed the same page and
+        // the real help written in `layer`/`ref`/`ext` was unreachable (#5527).
+        const requested = args[0];
+        if (HELP_DELEGATING_COMMANDS.has(requested)) {
+            // These three write richer help of their own; let them answer.
+        }
+        else {
+            const commandHelp = buildCommandHelp(VERSION, requested);
+            process.stdout.write((commandHelp ?? buildHelp(VERSION)) + '\n');
+            return;
+        }
+    }
     if (args.includes('--version') || args.includes('-v')) {
         process.stdout.write(`ifc-lite ${VERSION}\n`);
         return;
@@ -256,6 +97,11 @@ async function main() {
     const command = args[0];
     activeCommand = command;
     const commandArgs = args.slice(1);
+    if (commandArgs.includes('--out') && !COMMANDS_WITH_OUT.has(command)) {
+        fatal(`\`${command}\` does not write to a file: it has no --out. ` +
+            `Redirect its output instead, e.g. \`ifc-lite ${command} ... > out.json\`. ` +
+            `Commands that do take --out: ${[...COMMANDS_WITH_OUT].sort().join(', ')}.`);
+    }
     switch (command) {
         case 'info':
             await infoCommand(commandArgs);
@@ -362,6 +208,12 @@ async function main() {
         case 'delivery':
             await deliveryCommand(commandArgs);
             break;
+        case 'check':
+            await checkCommand(commandArgs);
+            break;
+        case 'flow':
+            await flowCommand(commandArgs);
+            break;
         default:
             process.stderr.write(`Unknown command: ${command}\n`);
             process.stderr.write(`Run 'ifc-lite --help' for usage.\n`);

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/loader.d.ts

@@ -1,5 +1,6 @@
 import { type IfcDataStore } from '@ifc-lite/parser';
 import { type BimContext } from '@ifc-lite/sdk';
+import { HeadlessBackend } from './headless-backend.js';
 /**
  * Parse an IFC file from disk into an IfcDataStore.
  * Suppresses parser console output for clean CLI experience.
@@ -19,6 +20,7 @@ export declare function loadIfcBytes(bytes: Uint8Array, label?: string): Promise
 export declare function createHeadlessContext(filePath: string): Promise<{
     bim: BimContext;
     store: IfcDataStore;
+    backend: HeadlessBackend;
 }>;
 /**
  * Create a BimContext that streams viewer commands to a running `ifc-lite view` server.

package/dist/loader.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"loader.d.ts","sourceRoot":"","sources":["../src/loader.ts"],"names":[],"mappings":"AAWA,OAAO,EAA+B,KAAK,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAClF,OAAO,EAAoB,KAAK,UAAU,EAA4D,MAAM,eAAe,CAAC;AAI5H;;;GAGG;AACH,wBAAsB,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,CAGzE;AAED;;;;;;GAMG;AACH,wBAAsB,YAAY,CAChC,KAAK,EAAE,UAAU,EACjB,KAAK,SAAU,GACd,OAAO,CAAC,YAAY,CAAC,CA6DvB;AAED;;GAEG;AACH,wBAAsB,qBAAqB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC;IAAE,GAAG,EAAE,UAAU,CAAC;IAAC,KAAK,EAAE,YAAY,CAAA;CAAE,CAAC,CAK/G;AAED;;;;;GAKG;AACH,wBAAsB,sBAAsB,CAC1C,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC;IAAE,GAAG,EAAE,UAAU,CAAC;IAAC,KAAK,EAAE,YAAY,CAAA;CAAE,CAAC,CAUnD"}
+{"version":3,"file":"loader.d.ts","sourceRoot":"","sources":["../src/loader.ts"],"names":[],"mappings":"AAWA,OAAO,EAA+B,KAAK,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAClF,OAAO,EAAoB,KAAK,UAAU,EAA4D,MAAM,eAAe,CAAC;AAC5H,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAGxD;;;GAGG;AACH,wBAAsB,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,CAGzE;AAED;;;;;;GAMG;AACH,wBAAsB,YAAY,CAChC,KAAK,EAAE,UAAU,EACjB,KAAK,SAAU,GACd,OAAO,CAAC,YAAY,CAAC,CAkGvB;AAED;;GAEG;AACH,wBAAsB,qBAAqB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC;IAAE,GAAG,EAAE,UAAU,CAAC;IAAC,KAAK,EAAE,YAAY,CAAC;IAAC,OAAO,EAAE,eAAe,CAAA;CAAE,CAAC,CAKzI;AAED;;;;;GAKG;AACH,wBAAsB,sBAAsB,CAC1C,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC;IAAE,GAAG,EAAE,UAAU,CAAC;IAAC,KAAK,EAAE,YAAY,CAAA;CAAE,CAAC,CAUnD"}

package/dist/loader.js

@@ -50,6 +50,35 @@ export async function loadIfcBytes(bytes, label = 'input') {
         process.stderr.write(`Error: ${label} is not a valid IFC/STEP file\n`);
         process.exit(1);
     }
+    // A STEP file ends with `END-ISO-10303-21;`. Its absence means the bytes are
+    // truncated -- a half-finished download, a killed export, a partial upload --
+    // and a truncated file does not fail to parse: it parses to a PREFIX. The
+    // scan stops wherever the bytes stop and reports whatever it got, so
+    // `ifc-lite info` answered "Entities: 59" and exited 0 for the first 4 KB of a
+    // real model, and "Schema: IFC4" for a 22-byte stub with no FILE_SCHEMA at
+    // all (#5532). A confidently wrong answer is worse than an error, because
+    // nothing downstream can tell it apart from a small model.
+    //
+    // Only the tail is decoded: these files reach hundreds of MB.
+    const tailStart = Math.max(0, bytes.byteLength - 256);
+    const tailSnippet = new TextDecoder('latin1').decode(bytes.subarray(tailStart));
+    if (!tailSnippet.includes('END-ISO-10303-21;')) {
+        process.stderr.write(`Error: ${label} is truncated: it starts like a STEP file but has no ` +
+            `END-ISO-10303-21; terminator, so any entity count or schema read from it ` +
+            `would describe only the part that arrived.\n`);
+        process.exit(1);
+    }
+    // A file with a header and no DATA section carries no entities at all. It is
+    // well-formed STEP, so the terminator check above passes; it is still not a
+    // model, and reporting a schema for it asserts something the file never said.
+    // Bounded, like the header scan: `DATA;` follows the header, and these files
+    // reach hundreds of MB -- decoding one whole would also risk V8's max string
+    // length. 64 KB is far more header than any exporter writes.
+    const headText = new TextDecoder('latin1').decode(bytes.subarray(0, Math.min(bytes.byteLength, 64 * 1024)));
+    if (!/^\s*DATA\s*;/m.test(headText)) {
+        process.stderr.write(`Error: ${label} has no DATA section, so it contains no IFC entities.\n`);
+        process.exit(1);
+    }
     const parser = new IfcParser();
     // Capture the parser's internal console.log/warn during parsing and route
     // them to logger.debug: silent by default (stdout stays clean for payloads),
@@ -88,7 +117,7 @@ export async function createHeadlessContext(filePath) {
     const store = await loadIfcFile(filePath);
     const backend = new HeadlessBackend(store, basename(filePath));
     const bim = createBimContext({ backend });
-    return { bim, store };
+    return { bim, store, backend };
 }
 /**
  * Create a BimContext that streams viewer commands to a running `ifc-lite view` server.