synthetic-factorio 0.0.1 → 0.3.0

package/README.md

@@ -1,45 +1,49 @@
-# Synthetic Factorio
-
-Synthetic Factorio nodeJS runtime for unit testing mods.
-
-This is **not** a Factorio emulator, it is not a game that can be played.
-
-```typescript
-import { ModManager, FactorioEngine } from 'synthetic-factorio';
-
-const manager = new ModManager();
-// install vanilla "mod" data from https://github.com/wube/factorio-data (requires git CLI)
-await manager.installVanillaMods();
-// install mod by name from mod portal (requires FACTORIO_USERNAME and FACTORIO_TOKEN env variables)
-await manager.installPortalMod('SimpleSeablock');
-// install a mod in development from local files
-manager.installDirectoryMod('my-mod', './my-mod-files', { clearCache: true });
-
-// initialize the synthetic factorio engine and specify the mods that should be active
-// vanilla "mods" need to be specified, including "base", however "core" does not need to be listed
-const engine = new FactorioEngine({
-    mods: ['base', 'space-age', 'quality', 'recycler', 'elevated-rails', 'my-mod']
-});
-// run all mods through their settings phase
-engine.runSettingsPhase();
-// customize settings for your specific test run
-engine.setSettings({ startup: { 'my-mod-setting': true } });
-// run all mods through their data phase
-engine.runDataPhase();
-
-// read the data.raw collection and run test assertions
-console.log(engine.getRawData()['item']['stone-furnace']);
-
-// run control phase - NOTE: control phase support is currently very limited
-engine.runControlPhase(['my-mod']);
-
-// run any registered on_init callbacks
-engine.triggerInit();
-
-// trigger an event with the payload of your choice
-// Partial on the generic and casts on the sub-properties are recommended to avoid the need to setup the entire event payload
-engine.triggerEvent<Partial<runtime.on_chunk_generated>>(defines.events.on_chunk_generated, {
-    position: { x: 0, y: 0 },
-    surface: { name: 'nauvis' } as runtime.LuaSurface,
-});
-```
+# Synthetic Factorio
+
+<!--Hidden version bump 4-->
+
+Synthetic Factorio nodeJS runtime for unit testing mods.
+
+This is **not** a Factorio emulator, it is not a game that can be played.
+
+```typescript
+// defines are imported from synthetic-factorio not factorio-types.
+// In factorio-types they're an ambient declaration, in synthetic-factorio they're a usable object.
+import { ModManager, FactorioEngine, defines } from 'synthetic-factorio';
+
+const manager = new ModManager();
+// install vanilla "mod" data from https://github.com/wube/factorio-data (requires git CLI)
+await manager.installVanillaMods();
+// install mod by name from mod portal (requires FACTORIO_USERNAME and FACTORIO_TOKEN env variables)
+await manager.installPortalMod('SimpleSeablock');
+// install a mod in development from local files
+manager.installDirectoryMod('my-mod', './my-mod-files', { clearCache: true });
+
+// initialize the synthetic factorio engine and specify the mods that should be active
+// vanilla "mods" need to be specified, including "base", however "core" does not need to be listed
+const engine = new FactorioEngine({
+    mods: ['base', 'space-age', 'quality', 'recycler', 'elevated-rails', 'my-mod']
+});
+// run all mods through their settings phase
+engine.runSettingsPhase();
+// customize settings for your specific test run
+engine.setSettings({ startup: { 'my-mod-setting': true } });
+// run all mods through their data phase
+engine.runDataPhase();
+
+// read the data.raw collection and run test assertions
+console.log(engine.getRawData()['item']['stone-furnace']);
+
+// run control phase - NOTE: control phase support is currently very limited
+engine.runControlPhase(['my-mod']);
+
+// run any registered on_init callbacks
+engine.triggerInit();
+
+// trigger an event with the payload of your choice
+// Partial on the generic and casts on the sub-properties are recommended to avoid the need to setup the entire event payload
+engine.triggerEvent<Partial<runtime.on_chunk_generated>>(defines.events.on_chunk_generated, {
+    position: { x: 0, y: 0 },
+    surface: { name: 'nauvis' } as runtime.LuaSurface,
+});
+```

package/dist/ModManager.d.ts

@@ -7,6 +7,11 @@ export interface ModManagerOptions {
      * Working directory for files like mod downloads
      */
     workingDir?: string;
+    /**
+     * Function to accept diagnostic logging, if not supplied then no diagnostics will be logged. Can be verbose, primarily intended for troubleshooting
+     * @param message Message to be logged
+     */
+    logger?: (message: string) => void;
 }
 export interface ModInstallOptions {
     /**
@@ -44,6 +49,7 @@ export interface ModPortalDownloadOptions extends ModDownloadOptions {
 export declare class ModManager {
     readonly modDir: string;
     readonly workingDir: string;
+    readonly log: (message: string) => void;
     constructor(options?: ModManagerOptions);
     /**
      * Download all vanilla "mod" data from https://github.com/wube/factorio-data

package/dist/ModManager.js

@@ -16,9 +16,11 @@ const vanillaMods = ['core', 'base', 'quality', 'recycler', 'elevated-rails', 's
 export class ModManager {
     modDir;
     workingDir;
+    log;
     constructor(options) {
         this.modDir = options?.modDir || modDir();
         this.workingDir = options?.workingDir || workingDir();
+        this.log = options?.logger || (() => { });
     }
     /**
      * Download all vanilla "mod" data from https://github.com/wube/factorio-data
@@ -28,13 +30,17 @@ export class ModManager {
     async installVanillaMods(options) {
         const run = promisify(exec);
         const gitDir = path.join(this.workingDir, 'factorio-data');
+        this.log(`Installing vanilla mods at ${gitDir}`);
         if (existsSync(gitDir) && options?.clearDownload) {
+            this.log(`gitDir ${gitDir} exists, deleting`);
             rmSync(gitDir, { recursive: true });
         }
         if (existsSync(gitDir) && options?.checkLatest) {
+            this.log(`Vanilla mod repo exists at ${gitDir}, pulling latest`);
             await run('git pull', { cwd: gitDir });
         }
         if (!existsSync(gitDir)) {
+            this.log(`Vanilla mod repo does not exist at ${gitDir}, cloning`);
             mkdirSync(this.workingDir, { recursive: true });
             await run('git clone --depth=1 https://github.com/wube/factorio-data.git', { cwd: this.workingDir });
         }
@@ -50,12 +56,18 @@ export class ModManager {
      */
     installDirectoryMod(modName, sourcePath, options) {
         const targetPath = this.getModPath(modName);
+        this.log(`Installing mod ${modName} to ${targetPath} from ${sourcePath}`);
         if (existsSync(targetPath) && options?.clearCache) {
+            this.log(`Removing existing mod ${modName} at ${targetPath}`);
             rmSync(targetPath, { recursive: true });
         }
         if (!existsSync(targetPath)) {
+            this.log(`Copying mod ${modName} from ${sourcePath} to ${targetPath}`);
             cpSync(sourcePath, targetPath, { recursive: true });
         }
+        else {
+            this.log(`Mod ${modName} already exists at ${targetPath}`);
+        }
     }
     /**
      * Downloads and installs a mod from Factorio's mod portal.
@@ -64,24 +76,29 @@ export class ModManager {
      * @param options Mod Installation Optiions
      */
     async installPortalMod(modName, options) {
+        this.log(`Installing ${modName} from portal`);
         let modInfo = undefined;
         let targetVersion = undefined;
         const downloadDir = path.join(this.workingDir, 'downloads');
         mkdirSync(downloadDir, { recursive: true });
         if (options?.version) {
             targetVersion = options?.version;
+            this.log(`Mod ${modName} installed at specific version ${targetVersion}`);
         }
         else if (options?.checkLatest) {
             modInfo = await this.getModInfo(modName);
             targetVersion = modInfo.releases.slice(-1)[0].version;
+            this.log(`Mod ${modName} latest version is ${targetVersion}`);
         }
         let zipPath = undefined;
         if (targetVersion) {
             zipPath = path.join(downloadDir, `${modName}_${targetVersion}.zip`);
+            this.log(`Installing mod ${modName} at target version ${targetVersion} to ${zipPath}`);
         }
         else {
             const modFiles = await glob(`${modName}_*.zip`, { cwd: downloadDir });
             if (modFiles.length) {
+                this.log(`Found ${modFiles.length} existing versions of mod ${modName}`);
                 let latest = '0.0.0';
                 for (const file of modFiles) {
                     const version = file.replace(/\.zip$/, '').split('_').slice(-1)[0];
@@ -89,10 +106,16 @@ export class ModManager {
                         latest = version;
                     }
                 }
+                this.log(`Latest downloaded version of ${modName} is ${latest}`);
                 zipPath = path.join(downloadDir, `${modName}_${latest}.zip`);
+                this.log(`Using zip path ${zipPath} for ${modName}`);
+            }
+            else {
+                this.log(`Did not find previously-installed version of ${modName}`);
             }
         }
         if (zipPath && options?.clearDownload) {
+            this.log(`Deleting existing zip at ${zipPath} for ${modName}`);
             rmSync(zipPath);
         }
         if (!zipPath) {
@@ -100,7 +123,9 @@ export class ModManager {
                 modInfo = await this.getModInfo(modName);
             }
             targetVersion = modInfo.releases.slice(-1)[0].version;
+            this.log(`Found ${targetVersion} version of ${modName} from mod info`);
             zipPath = path.join(downloadDir, `${modName}_${targetVersion}.zip`);
+            this.log(`Using zip path ${zipPath} for ${modName}`);
         }
         if (!existsSync(zipPath)) {
             if (!modInfo) {
@@ -111,6 +136,7 @@ export class ModManager {
                 let url = modInfo.releases.find(r => r.version === targetVersion)?.download_url;
                 if (url) {
                     modDownloadUrl = url;
+                    this.log(`Download url for ${modName} at target version ${targetVersion} is ${modDownloadUrl}`);
                 }
                 else {
                     throw new Error(`Cannot find version ${targetVersion} of mod ${modName}`);
@@ -118,6 +144,7 @@ export class ModManager {
             }
             else {
                 modDownloadUrl = modInfo.releases.slice(-1)[0].download_url;
+                this.log(`Download url for ${modName} is ${modDownloadUrl}`);
             }
             if (!process.env.FACTORIO_USERNAME) {
                 throw new Error('Cannot download mod, env variable FACTORIO_USERNAME is not set');
@@ -135,10 +162,12 @@ export class ModManager {
         }
         let isOutdated = false;
         const targetPath = this.getModPath(modName);
+        this.log(`Using path ${targetPath} for ${modName}`);
         if (existsSync(targetPath) && targetVersion) {
             const modInfo = getModInfo(targetPath);
             if (modInfo.version != targetVersion) {
                 isOutdated = true;
+                this.log(`Mod ${modName} is outdated`);
             }
         }
         await this.installZipMod(modName, zipPath, { ...options, clearCache: isOutdated ? true : options?.clearCache });
@@ -146,10 +175,17 @@ export class ModManager {
             const dependencies = getDependencies(this.getModPath(modName));
             for (let dependency of dependencies.required) {
                 if (!vanillaMods.includes(dependency) && !options?.omitDependencies?.includes(dependency)) {
+                    this.log(`Installing dependency ${dependency} for ${modName}`);
                     await this.installPortalMod(dependency, { ...options, version: undefined });
                 }
+                else {
+                    this.log(`Not necessary to install dependency ${dependency} for ${modName}`);
+                }
             }
         }
+        else {
+            this.log(`Skipping dependencies for ${modName}`);
+        }
     }
     async getModInfo(modName) {
         const response = await fetch(`https://mods.factorio.com/api/mods/${modName}`);
@@ -163,16 +199,24 @@ export class ModManager {
      */
     async installZipMod(modName, sourcePath, options) {
         const targetPath = this.getModPath(modName);
+        this.log(`Installing ${modName} as zip from ${sourcePath} to ${targetPath}`);
         if (existsSync(targetPath) && options?.clearCache) {
+            this.log(`Deleting existing mod ${modName} at ${targetPath}`);
             rmSync(targetPath, { recursive: true });
         }
         if (!existsSync(targetPath)) {
             const unzipDir = path.join(this.workingDir, 'unzip');
+            this.log(`Unzipping ${modName} from ${sourcePath} to ${unzipDir}`);
             mkdirSync(unzipDir, { recursive: true });
             await extractZip(sourcePath, { dir: unzipDir });
             // Mod contents are in a single dir inside the zip file, and the dir can have any name so we need to handle that
-            let dirs = readdirSync(unzipDir);
-            renameSync(path.join(unzipDir, dirs[0]), targetPath);
+            const dirs = readdirSync(unzipDir);
+            const sourceDir = path.join(unzipDir, dirs[0]);
+            this.log(`Renaming ${sourceDir} to ${targetPath} for ${modName}`);
+            renameSync(sourceDir, targetPath);
+        }
+        else {
+            this.log(`Mod zip ${modName} already exists at ${targetPath}, no action needed`);
         }
     }
     getModPath(modName) {