@faicad/faijs 0.22.2 → 0.29.5

package/dist/node-host/cli.d.ts

@@ -17,7 +17,7 @@
  *                                       — (view) 单视图方向（默认 front）
  *   --sheet <front,top,right,iso>       — (view) 多视图图纸（projectSheet；与 --view 互斥）
  */
-import type { StdlibNamespace } from '../runtime-state.js';
+import type { LibNamespace } from '../runtime-state.js';
 import type { ExecutionMode } from '../cad-runtime/ports.js';
 import type { ViewSpec } from '../api/view/view-camera.js';
 /** Options accepted by the `check` command. */
@@ -26,6 +26,19 @@ export interface CliCheckOptions {
     assetsDir?: string;
     /** Extra fonts directory used by the node ports. */
     fontsDir?: string;
+    /**
+     * Extra cad-namespace entries the host merges at run time (`cad.sketch`
+     * from @faicad/faijs-sketch).
+     *
+     * I-group (2026-10-03): the unknown-op guard compares the script's callees
+     * against `symbolTableNames()`, which knows only the STATIC table. A host
+     * that merges those libraries and passes them to {@link cliRun} therefore
+     * got `unknown op: cad.sketch is not in the cad namespace` from every check
+     * of a perfectly runnable script — `rebased-sweep.ts` reported it for every
+     * product in a corpus sweep. Check and run must see the same namespace, so
+     * the caller states its merged entries here.
+     */
+    libs?: Record<string, unknown>;
 }
 /** Options accepted by the `run` command. */
 export interface CliRunOptions {
@@ -37,13 +50,19 @@ export interface CliRunOptions {
     fontsDir?: string;
     /** Default font path used by the node ports. */
     defaultFontPath?: string;
-    /** Host-injected library namespace (includes cad — the CLI entry faijs-cli.ts passes createInternalStdlib; core does not assemble it by default). */
-    libs?: Record<string, StdlibNamespace>;
+    /** Host-injected library namespace (includes cad — the CLI entry faijs-cli.ts passes createApiNamespace; core does not assemble it by default). */
+    libs?: Record<string, LibNamespace>;
     /**
      * 项目根（多文件 §4.5）：相对 import 的解析基准，moduleKey = 相对它的路径。
      * 缺省由入口文件向上找最近的 package.json。
      */
     projectRoot?: string;
+    /**
+     * 连带导出隐藏终端（默认 false）。keep / keepHidden 保留的源几何默认不产出
+     * （隐藏的语义即"保留但不出现在产物里"）；置 true 恢复旧行为，把 hidden 终端
+     * 也一并写盘（多为诊断用途）。
+     */
+    includeHidden?: boolean;
 }
 /** Result of the `check` (dry-run validation) command. */
 export interface CliCheckResult {
@@ -88,7 +107,7 @@ export interface CliViewOptions {
     /** Default font path used by the node ports. */
     defaultFontPath?: string;
     /** Host-injected library namespace (includes cad). */
-    libs?: Record<string, StdlibNamespace>;
+    libs?: Record<string, LibNamespace>;
     /** Project root for relative .fai.js imports. */
     projectRoot?: string;
     /** Shape variable name to project; default resolves terminals like `run`. */
@@ -126,6 +145,24 @@ export declare function cliCheck(filePath: string, _opts?: CliCheckOptions): Cli
  * @returns the run result describing success or failure
  */
 export declare function cliRun(filePath: string, outPath: string, opts?: CliRunOptions): Promise<CliRunResult>;
+/**
+ * 选出「可导出」的终端：默认剔除 hidden。
+ *
+ * 隐藏终端 = 「保留但不产出」（`keep` / `keepHidden` 语义，R5）。导出层必须默认跳过，
+ * 否则布尔运算保留的源几何会对每个 hidden 终端各写一个 `out.step_<i>_<name>` 产物，
+ * 让一个逻辑形状看起来像 N 个（FCStd port 的 `solids 1vsN` 失配即由此而来）。
+ * 需要旧行为（连同隐藏源一起写出，多用于诊断）时显式传 `includeHidden=true`。
+ *
+ * @param terminals - 存活终端集合（含 `hidden` 标记）
+ * @param includeHidden - 是否连同隐藏终端一起导出，缺省 false
+ * @returns `exportable`（可导出终端）与 `hiddenCount`（被剔除的隐藏终端数）
+ */
+export declare function selectExportableTerminals<T extends {
+    hidden?: boolean;
+}>(terminals: readonly T[], includeHidden?: boolean): {
+    exportable: T[];
+    hiddenCount: number;
+};
 /**
  * Execute the `view` command: execute a .fai.js file and write view SVG(s).
  *
@@ -156,13 +193,14 @@ export declare function parseArgs(argv: string[]): {
     view?: string;
     sheet?: string;
     part?: string;
+    includeHidden?: boolean;
 };
 /**
  * CLI main entry point (called by scripts/faijs-cli.ts).
  *
  * @param argv - the raw process argument list
- * @param libs - host-injected library namespace (includes cad — faijs-cli.ts passes createInternalStdlib; core does not assemble it by default)
+ * @param libs - host-injected library namespace (includes cad — faijs-cli.ts passes createApiNamespace; core does not assemble it by default)
  * @returns the process exit code (0 on success, non-zero on failure)
  */
-export declare function cliMain(argv: string[], libs?: Record<string, StdlibNamespace>): Promise<number>;
+export declare function cliMain(argv: string[], libs?: Record<string, LibNamespace>): Promise<number>;
 //# sourceMappingURL=cli.d.ts.map

package/dist/node-host/cli.d.ts.map

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

package/dist/node-host/cli.js

@@ -42,9 +42,9 @@ const CLI_SCOPED_PREFIX = '@faicad/';
 /** 已登记短名 → scoped 全名归一表（仅收录 `@faicad/` 范围内的库，防同名陌生人包）。 */
 const CLI_SHORT_NAMES = {
     'sheetmetal': '@faicad/sheetmetal',
-    'cq-compat': '@faicad/cq-compat',
-    'fai-cq-gears': '@faicad/fai-cq-gears',
-    'fai-cq-warehouse': '@faicad/fai-cq-warehouse',
+    'faijs-cadquery': '@faicad/faijs-cadquery',
+    'faijs-gears': '@faicad/faijs-gears',
+    'faijs-fasteners': '@faicad/faijs-fasteners',
 };
 /**
  * 读库 package.json 的 `faijs.autoLift` 字段（D3-autoLift 外置，§9.4）：
@@ -144,11 +144,19 @@ export function cliCheck(filePath, _opts) {
     // D11 (2026-09-28): unknown-op guard. check() is syntax+reference only — an
     // op the cad namespace doesn't have used to pass `check` clean and die at
     // runtime (e.g. `cad.sketch is not a function` when a host forgets to merge
-    // the sketch/draw libraries). Compare the script's callees against the
+    // the sketch library). Compare the script's callees against the
     // symbol-table union view (platform + registered library entries) and fail
     // the check on any unknown callee.
     if (result.ok && result.script) {
         const known = new Set(symbolTableNames());
+        // Ops the host merges at run time are not in the static table; accept the
+        // names it declares as known so check agrees with the run that follows.
+        for (const ns of Object.values(_opts?.libs ?? {})) {
+            if (ns && typeof ns === 'object') {
+                for (const key of Object.keys(ns))
+                    known.add(key);
+            }
+        }
         const unknown = [...new Set(result.script.callees)].filter((n) => !known.has(n));
         for (const name of unknown) {
             errors.push({
@@ -215,7 +223,7 @@ export async function cliRun(filePath, outPath, opts) {
     // exception — the census and batch driver treat a throw as a process crash,
     // while `{ ok: false, error }` keeps it a per-file, classifiable failure.
     try {
-        return await exportExecutionResult(outPath, ext, execResult, terminals);
+        return await exportExecutionResult(outPath, ext, execResult, terminals, opts?.includeHidden ?? false);
     }
     catch (e) {
         return {
@@ -225,9 +233,38 @@ export async function cliRun(filePath, outPath, opts) {
         };
     }
 }
+/**
+ * 选出「可导出」的终端：默认剔除 hidden。
+ *
+ * 隐藏终端 = 「保留但不产出」（`keep` / `keepHidden` 语义，R5）。导出层必须默认跳过，
+ * 否则布尔运算保留的源几何会对每个 hidden 终端各写一个 `out.step_<i>_<name>` 产物，
+ * 让一个逻辑形状看起来像 N 个（FCStd port 的 `solids 1vsN` 失配即由此而来）。
+ * 需要旧行为（连同隐藏源一起写出，多用于诊断）时显式传 `includeHidden=true`。
+ *
+ * @param terminals - 存活终端集合（含 `hidden` 标记）
+ * @param includeHidden - 是否连同隐藏终端一起导出，缺省 false
+ * @returns `exportable`（可导出终端）与 `hiddenCount`（被剔除的隐藏终端数）
+ */
+export function selectExportableTerminals(terminals, includeHidden = false) {
+    const hiddenCount = terminals.reduce((n, t) => (t.hidden ? n + 1 : n), 0);
+    const exportable = includeHidden ? [...terminals] : terminals.filter((t) => !t.hidden);
+    return { exportable, hiddenCount };
+}
 /** Export an executed result to `outPath` (shared body of cliRun's export path). */
-async function exportExecutionResult(outPath, ext, execResult, terminals) {
-    if (terminals.length === 0) {
+async function exportExecutionResult(outPath, ext, execResult, terminals, includeHidden = false) {
+    const { exportable, hiddenCount } = selectExportableTerminals(terminals, includeHidden);
+    // 装配导出（writeAssemblyStep 的兜底路径）同样不得带出隐藏终端；includeHidden 时传 undefined。
+    const hiddenTerminals = includeHidden
+        ? undefined
+        : new Set(terminals.filter((t) => t.hidden).map((t) => String(t.id)));
+    // 有终端但全部隐藏 → 明确报错（不静默回退到「最后一个 output」，那等于把隐藏源漏出去）。
+    if (!includeHidden && exportable.length === 0 && hiddenCount > 0) {
+        return {
+            ok: false,
+            error: `All ${hiddenCount} live terminal(s) are hidden — nothing to export (pass includeHidden to export them)`,
+        };
+    }
+    if (exportable.length === 0) {
         // No terminals — use last output
         const outputNames = [...execResult.outputs.keys()];
         if (outputNames.length === 0) {
@@ -242,15 +279,15 @@ async function exportExecutionResult(outPath, ext, execResult, terminals) {
         return writeOutput(outPath, ext, shape, solidEntry ? { solid: solidEntry.solid, kernel: solidEntry.kernel } : undefined);
     }
     // Single terminal
-    if (terminals.length === 1) {
-        const terminal = terminals[0];
+    if (exportable.length === 1) {
+        const terminal = exportable[0];
         const shape = execResult.outputs.get(terminal.id);
         if (!shape) {
             return { ok: false, error: `No output for terminal "${terminal.id}"` };
         }
         // Assembly (compound with behavior) → expand members with colors
         if (!('positions' in shape) || !('indices' in shape)) {
-            const asmResult = writeAssemblyStep(outPath, ext, shape, execResult);
+            const asmResult = writeAssemblyStep(outPath, ext, shape, execResult, hiddenTerminals);
             if (asmResult)
                 return asmResult;
         }
@@ -259,21 +296,21 @@ async function exportExecutionResult(outPath, ext, execResult, terminals) {
     }
     // Multiple terminals — write each to a separate file
     // First, check if any terminal is a compound (assembly) — export it as a single STEP
-    for (let i = 0; i < terminals.length; i++) {
-        const terminal = terminals[i];
+    for (let i = 0; i < exportable.length; i++) {
+        const terminal = exportable[i];
         const shape = execResult.outputs.get(terminal.id);
         if (!shape)
             continue;
         if (!('positions' in shape) || !('indices' in shape)) {
             // Compound terminal — try assembly STEP export
-            const asmResult = writeAssemblyStep(outPath, ext, shape, execResult);
+            const asmResult = writeAssemblyStep(outPath, ext, shape, execResult, hiddenTerminals);
             if (asmResult)
                 return asmResult;
         }
     }
     // Then export non-compound terminals
-    for (let i = 0; i < terminals.length; i++) {
-        const terminal = terminals[i];
+    for (let i = 0; i < exportable.length; i++) {
+        const terminal = exportable[i];
         const shape = execResult.outputs.get(terminal.id);
         if (!shape)
             continue;
@@ -306,6 +343,7 @@ function parseViewArg(v) {
 /**
  * 选出待投影的 shape 列表（`--part` 指定，或按终端自动选择，与 `run` 一致）：
  * 只保留带 mesh 的 shape（compound/assembly 无 mesh，无法投影，跳过）。
+ * 隐藏终端（keep/keepHidden 保留的源几何）默认不投影——与 `run` 同口径。
  */
 function selectViewShapes(execResult, part) {
     const outputs = execResult.outputs;
@@ -316,8 +354,11 @@ function selectViewShapes(execResult, part) {
             return [{ name: part, shape }];
         return [];
     }
-    const terminals = execResult.terminals ?? [];
-    const ids = terminals.length > 0 ? terminals.map((t) => t.id) : [...outputs.keys()];
+    // 隐藏终端默认不投影。全部终端皆隐藏 → 空集（**不**回退到「所有 outputs」，
+    // 否则会把全部中间量也画出来，与 run 的「全隐藏即无可导出」语义相悖）。
+    const allTerminals = execResult.terminals ?? [];
+    const { exportable: terminals } = selectExportableTerminals(allTerminals);
+    const ids = allTerminals.length > 0 ? terminals.map((t) => t.id) : [...outputs.keys()];
     const out = [];
     for (const id of ids) {
         const shape = outputs.get(id) ?? outputs.get(asPartName(String(id)));
@@ -405,10 +446,10 @@ export async function cliView(filePath, outPath, opts) {
 /**
  * 写出输出文件。
  *
- * 按零件类型分别处理 STEP 导出：
- * - 有 BREP solid → 精确 STEP（exportStepFromSolid，ADVANCED_FACE）
- * - 无 BREP solid → 三角化 STEP（exportStep/meshesToStep，faceted）
- * - STL：无论是否 BREP，都取 mesh Shape 导出
+ * 按零件类型分别处理导出：
+ * - STL：取网格载荷（BREP 零件先经内核三角化），无重建。
+ * - STEP：有 BREP solid → 精确 STEP（ADVANCED_FACE）；无 BREP solid → 该零件的
+ *   三角网格经重建管线导出（exportModelSync 内的 mesh 条目通路）。
  *
  * keep-syntax §5.1：outputs 现含 compound（group/assembly 产物，无 mesh）；
  * compound 无法导出，给出明确错误（此前"不在 outputs 中"是静默失败）。
@@ -453,7 +494,7 @@ function writeOutput(outPath, ext, shape, brepSolid) {
  * Returns null if the compound has no assembly behavior (falls through to
  * regular writeOutput), or a CliRunResult on success/failure.
  */
-function writeAssemblyStep(outPath, ext, compound, execResult) {
+function writeAssemblyStep(outPath, ext, compound, execResult, hiddenTerminals) {
     if (ext !== 'step' && ext !== 'stp')
         return null;
     const slot = ensureSlot(compound);
@@ -509,6 +550,10 @@ function writeAssemblyStep(outPath, ext, compound, execResult) {
     // Fallback: export all brepSolids (covers compounds where memberNames wasn't propagated)
     if (entries.length === 0 && execResult.brepSolids) {
         for (const [key, solidEntry] of execResult.brepSolids) {
+            // 隐藏终端（keep/keepHidden 保留的源几何）不得借这条兜底路径落盘——
+            // 与主导出路径同一判据（includeHidden 时 hiddenTerminals 传 undefined，不过滤）。
+            if (hiddenTerminals?.has(String(key)))
+                continue;
             if (!kernel)
                 kernel = solidEntry.kernel;
             entries.push({
@@ -546,6 +591,7 @@ export function parseArgs(argv) {
     let view;
     let sheet;
     let part;
+    let includeHidden;
     for (let i = 1; i < args.length; i++) {
         const arg = args[i];
         if (arg === '--out' || arg === '-o') {
@@ -575,21 +621,24 @@ export function parseArgs(argv) {
         else if (arg === '--part') {
             part = args[++i];
         }
+        else if (arg === '--include-hidden') {
+            includeHidden = true;
+        }
         else if (!file && !arg.startsWith('-')) {
             file = arg;
         }
     }
-    return { command, file, out, mode, assetsDir, fontsDir, projectRoot, view, sheet, part };
+    return { command, file, out, mode, assetsDir, fontsDir, projectRoot, view, sheet, part, includeHidden };
 }
 /**
  * CLI main entry point (called by scripts/faijs-cli.ts).
  *
  * @param argv - the raw process argument list
- * @param libs - host-injected library namespace (includes cad — faijs-cli.ts passes createInternalStdlib; core does not assemble it by default)
+ * @param libs - host-injected library namespace (includes cad — faijs-cli.ts passes createApiNamespace; core does not assemble it by default)
  * @returns the process exit code (0 on success, non-zero on failure)
  */
 export async function cliMain(argv, libs) {
-    const { command, file, out, mode, assetsDir, fontsDir, projectRoot, view, sheet, part } = parseArgs(argv);
+    const { command, file, out, mode, assetsDir, fontsDir, projectRoot, view, sheet, part, includeHidden } = parseArgs(argv);
     if (!command) {
         process.stderr.write('Usage: faijs-cli <check|run|view> <file.fai.js> [options]\n');
         process.stderr.write('  check <file>              DryRun validation\n');
@@ -599,6 +648,7 @@ export async function cliMain(argv, libs) {
         process.stderr.write('  --assets <dir>            Asset directory\n');
         process.stderr.write('  --fonts <dir>             Extra fonts directory\n');
         process.stderr.write('  --project-root <dir>      Project root for relative .fai.js imports\n');
+        process.stderr.write('  --include-hidden          (run) also export hidden terminals (keep/keepHidden sources; default off)\n');
         process.stderr.write('  --part <name>             (view) shape variable to project (default: terminals)\n');
         process.stderr.write('  --view <dir>              (view) single view: front|back|top|bottom|left|right|iso|"x,y,z" (default front)\n');
         process.stderr.write('  --sheet <a,b,c>           (view) multi-view sheet: front,top,right,iso (mutually exclusive with --view)\n');
@@ -634,7 +684,7 @@ export async function cliMain(argv, libs) {
             return 1;
         }
         const outPath = resolve(out);
-        const result = await cliRun(filePath, outPath, { mode, assetsDir, fontsDir, projectRoot, libs });
+        const result = await cliRun(filePath, outPath, { mode, assetsDir, fontsDir, projectRoot, libs, includeHidden });
         if (result.ok) {
             process.stdout.write(`✓ ${filePath} → ${outPath} (${result.outputFormat})\n`);
             if (result.infos && result.infos.length > 0) {