@helix3/helix-cli 0.1.18-helix3.367 → 0.1.18-helix3.368

package/dist/bridge/zipSource.d.ts

@@ -0,0 +1,27 @@
+import { type ArchiveLimits } from '../sceneImport/archive';
+/**
+ * Caps for a mod archive downloaded from a repository. Entry count matches the BeamNG importer's own
+ * 50,000-file source ceiling; the byte ceilings are per entry and in total, and the compression-ratio
+ * guard from the shared archive reader still applies.
+ */
+export declare const ZIP_SOURCE_LIMITS: ArchiveLimits;
+export type PreparedBridgeSource = {
+    /** Directory (or the original file) the Bridge should read. */
+    path: string;
+    /** Set when `path` is a temporary extraction of this ZIP. */
+    extractedFrom?: {
+        archive: string;
+        sha256: string;
+        entries: number;
+        uncompressedBytes: number;
+    };
+    cleanup(): Promise<void>;
+};
+export declare function isZipSourcePath(source: string): boolean;
+/**
+ * Safely extract a `.zip` source to a private temporary directory. The archive is rejected as a whole
+ * if any entry is absolute, climbs out with `..`, is duplicated, exceeds the size caps, or looks like a
+ * decompression bomb; members are written with exclusive-create into an empty real directory that is
+ * removed by `cleanup()` (and on process exit). A non-zip source is returned unchanged.
+ */
+export declare function prepareBridgeSource(source: string, onProgress?: (message: string) => void, limits?: ArchiveLimits): Promise<PreparedBridgeSource>;

package/dist/bridge/zipSource.js

@@ -0,0 +1,90 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ZIP_SOURCE_LIMITS = void 0;
+exports.isZipSourcePath = isZipSourcePath;
+exports.prepareBridgeSource = prepareBridgeSource;
+const node_fs_1 = require("node:fs");
+const promises_1 = require("node:fs/promises");
+const node_os_1 = require("node:os");
+const node_path_1 = require("node:path");
+const archive_1 = require("../sceneImport/archive");
+/**
+ * Caps for a mod archive downloaded from a repository. Entry count matches the BeamNG importer's own
+ * 50,000-file source ceiling; the byte ceilings are per entry and in total, and the compression-ratio
+ * guard from the shared archive reader still applies.
+ */
+exports.ZIP_SOURCE_LIMITS = {
+    maxEntries: 50_000,
+    maxEntryBytes: 1_073_741_824,
+    maxTotalBytes: 8 * 1_073_741_824,
+    maxCompressionRatio: 1_000,
+};
+/** Archive bookkeeping that is never part of a mod's content. */
+const JUNK = /(?:^|\/)(?:__MACOSX|\.DS_Store|Thumbs\.db)(?:\/|$)/;
+function isZipSourcePath(source) {
+    const path = (0, node_path_1.resolve)(source);
+    if ((0, node_path_1.extname)(path).toLowerCase() !== '.zip')
+        return false;
+    try {
+        return (0, node_fs_1.statSync)(path).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+/** A mod zipped with one wrapper folder (`MyMod/vehicles/...`) is read from inside that folder. */
+function unwrapSingleFolder(root) {
+    const entries = (0, node_fs_1.readdirSync)(root, { withFileTypes: true });
+    if (entries.some((entry) => entry.isDirectory() && entry.name === 'vehicles'))
+        return root;
+    const folders = entries.filter((entry) => entry.isDirectory());
+    if (folders.length === 1 && entries.length === 1) {
+        return unwrapSingleFolder((0, node_path_1.join)(root, folders[0].name));
+    }
+    return root;
+}
+/**
+ * Safely extract a `.zip` source to a private temporary directory. The archive is rejected as a whole
+ * if any entry is absolute, climbs out with `..`, is duplicated, exceeds the size caps, or looks like a
+ * decompression bomb; members are written with exclusive-create into an empty real directory that is
+ * removed by `cleanup()` (and on process exit). A non-zip source is returned unchanged.
+ */
+async function prepareBridgeSource(source, onProgress, limits = exports.ZIP_SOURCE_LIMITS) {
+    if (!isZipSourcePath(source))
+        return { path: source, cleanup: async () => { } };
+    const archive = (0, node_path_1.resolve)(source);
+    const sha256 = await (0, archive_1.sha256File)(archive);
+    const inventory = await (0, archive_1.inventorySourceArchive)(archive, sha256, limits);
+    const members = inventory.entries
+        .filter((entry) => !entry.directory && !JUNK.test(entry.path))
+        .map((entry) => entry.path);
+    if (members.length === 0)
+        throw new Error(`Bridge source archive is empty: ${archive}`);
+    const scratch = await (0, promises_1.mkdtemp)((0, node_path_1.join)((0, node_os_1.tmpdir)(), 'helix-zip-source-'));
+    const exitCleanup = () => { try {
+        (0, node_fs_1.rmSync)(scratch, { recursive: true, force: true });
+    }
+    catch { /* best effort */ } };
+    process.once('exit', exitCleanup);
+    const cleanup = async () => {
+        process.removeListener('exit', exitCleanup);
+        await (0, promises_1.rm)(scratch, { recursive: true, force: true });
+    };
+    try {
+        const output = (0, node_path_1.join)(scratch, 'source');
+        onProgress?.(`extracting ${members.length} file(s) from ${archive} (${inventory.uncompressedBytes} bytes)`);
+        await (0, archive_1.extractArchiveMembers)({ archivePath: archive, expectedSha256: sha256, members, outputDir: output, limits });
+        return {
+            path: unwrapSingleFolder(output),
+            extractedFrom: {
+                archive, sha256, entries: members.length, uncompressedBytes: inventory.uncompressedBytes,
+            },
+            cleanup,
+        };
+    }
+    catch (error) {
+        await cleanup();
+        throw error;
+    }
+}
+//# sourceMappingURL=zipSource.js.map

package/dist/bridge/zipSource.js.map

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

package/dist/index.js

@@ -142,6 +142,20 @@ function bridgeInputs(values) {
     }
     return inputs;
 }
+/**
+ * Bridge sources may be a `.zip` as downloaded (a BeamNG mod from the repository, say): it is extracted
+ * safely to a temporary directory for the duration of the command and removed afterwards.
+ */
+async function withBridgeSource(source, run) {
+    const { prepareBridgeSource } = await Promise.resolve().then(() => __importStar(require('./bridge/zipSource')));
+    const prepared = await prepareBridgeSource(source, (message) => console.error(`  ${message}`));
+    try {
+        return await run(prepared.path);
+    }
+    finally {
+        await prepared.cleanup();
+    }
+}
 function bridgeTerminalText(value) {
     return value.replace(/[\u0000-\u001f\u007f-\u009f\u2028\u2029]/gu, (character) => {
         if (character === '\n')
@@ -178,12 +192,12 @@ const bridge = program
 bridge
     .command('detect')
     .description('Fingerprint a source and identify its engine, format, and likely content domain')
-    .argument('<source>', 'file or project directory')
+    .argument('<source>', 'file, project directory, or a .zip of one (extracted safely to a temp dir)')
     .option('--json', 'print the machine-readable detection record')
     .action(async (source, opts) => {
     try {
         const { detectBridgeSource } = await Promise.resolve().then(() => __importStar(require('./bridge')));
-        const detection = await detectBridgeSource(source);
+        const detection = await withBridgeSource(source, (resolved) => detectBridgeSource(resolved));
         if (opts.json)
             console.log(JSON.stringify(detection, null, 2));
         else {
@@ -201,13 +215,13 @@ bridge
 bridge
     .command('inspect')
     .description('Inspect a source and show its detected structure plus viable import goals')
-    .argument('<source>', 'file or project directory')
+    .argument('<source>', 'file, project directory, or a .zip of one (extracted safely to a temp dir)')
     .option('--plugin-dir <paths...>', 'also discover local plugins from these directories')
     .option('--json', 'print machine-readable inspection and plans')
     .action(async (source, opts) => {
     try {
         const { buildBridgePlan, detectBridgeSource, loadBridgePlugins } = await Promise.resolve().then(() => __importStar(require('./bridge')));
-        const detection = await detectBridgeSource(source);
+        const detection = await withBridgeSource(source, (resolved) => detectBridgeSource(resolved));
         const plugins = loadBridgePlugins(opts.pluginDir);
         const plans = ['asset', 'character', 'addon', 'scene', 'animation']
             .map((type) => buildBridgePlan(detection, { type, target: 'web' }, plugins))
@@ -229,7 +243,7 @@ bridge
 bridge
     .command('plan')
     .description('Resolve installed plugin capabilities into a deterministic conversion graph')
-    .argument('<source>', 'file or project directory')
+    .argument('<source>', 'file, project directory, or a .zip of one (e.g. a BeamNG mod as downloaded; extracted safely to a temp dir)')
     .option('--type <type>', 'auto, asset, character, addon, scene, animation, or extract', 'auto')
     .option('--target <target>', 'web, unreal, mobile, or canonical', 'web')
     .option('--plugin <ids...>', 'restrict non-built-in plugins to these installed ids')
@@ -238,12 +252,12 @@ bridge
     .option('--eye-texture <image>', 'MetaHuman baked eye texture override (default: packaged canonical bake from PR #99)')
     .option('--canonical <glb>', 'canonical helix-humanoid body override')
     .option('--map <json>', 'custom skeleton/bone map')
-    .option('--input <name=path...>', 'immutable named plugin input; repeat for multiple inputs')
+    .option('--input <name=path...>', 'immutable named plugin input; repeat for multiple inputs (BeamNG: palette=<palette.json>, beamngCommon=<index.json>, beamngEngine=<engine.json> with {"cylinders": N} to override the derived cylinder count)')
     .option('--json', 'print the machine-readable plan')
     .action(async (source, opts) => {
     try {
         const { resolveBridgePlan } = await Promise.resolve().then(() => __importStar(require('./bridge')));
-        const plan = await resolveBridgePlan(source, {
+        const plan = await withBridgeSource(source, (resolved) => resolveBridgePlan(resolved, {
             type: bridgeType(opts.type),
             target: bridgeTarget(opts.target),
             plugin: opts.plugin,
@@ -253,7 +267,7 @@ bridge
             canonical: opts.canonical,
             map: opts.map,
             inputs: bridgeInputs(opts.input),
-        });
+        }));
         console.log(opts.json ? JSON.stringify(plan, null, 2) : renderBridgePlan(plan));
         if (plan.blockers.length > 0)
             process.exitCode = 2;
@@ -265,7 +279,7 @@ bridge
 bridge
     .command('import')
     .description('Detect, plan, convert, validate, package, and write deterministic provenance')
-    .argument('<source>', 'file or project directory')
+    .argument('<source>', 'file, project directory, or a .zip of one (e.g. a BeamNG mod as downloaded; extracted safely to a temp dir)')
     .option('--type <type>', 'auto, asset, character, addon, scene, animation, or extract', 'auto')
     .option('--target <target>', 'web, unreal, mobile, or canonical', 'web')
     .option('-o, --output <directory>', 'empty output directory', './bridge-out')
@@ -275,7 +289,7 @@ bridge
     .option('--eye-texture <image>', 'MetaHuman baked eye texture override (default: packaged canonical bake from PR #99)')
     .option('--canonical <glb>', 'canonical helix-humanoid body override')
     .option('--map <json>', 'custom skeleton/bone map')
-    .option('--input <name=path...>', 'immutable named plugin input; repeat for multiple inputs')
+    .option('--input <name=path...>', 'immutable named plugin input; repeat for multiple inputs (BeamNG: palette=<palette.json>, beamngCommon=<index.json>, beamngEngine=<engine.json> with {"cylinders": N} to override the derived cylinder count)')
     .option('--expect-plan-key <sha256>', 'execute only if the freshly resolved plan has this exact key')
     .option('--allow-permission <permissions...>', 'permissions approved for community/local plugins; repeat or comma-separate')
     .option('--dry-run', 'plan only; write and execute nothing')
@@ -285,7 +299,7 @@ bridge
     .action(async (source, opts) => {
     try {
         const { importWithBridge } = await Promise.resolve().then(() => __importStar(require('./bridge')));
-        const result = await importWithBridge(source, {
+        const result = await withBridgeSource(source, (resolved) => importWithBridge(resolved, {
             type: bridgeType(opts.type),
             target: bridgeTarget(opts.target),
             output: opts.output,
@@ -302,7 +316,7 @@ bridge
             keepStage: opts.keepStage,
             allowUntexturedBodyGeometry: opts.allowUntexturedBodyGeometry,
             onProgress: (message) => console.error(`  ${message}`),
-        });
+        }));
         if (opts.json)
             console.log(JSON.stringify(result, null, 2));
         else if (opts.dryRun)