modpack-lock 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 N. Escobar
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,103 @@
+
+<a href="https://github.com/nickesc/modpack-lock"><img alt="Source: Github" src="https://img.shields.io/badge/source-github-brightgreen?style=for-the-badge&logo=github&labelColor=%23505050"></a>
+<a href="https://www.npmjs.com/package/modpack-lock"><img alt="NPM: npmjs.com/package/modpack-lock" src="https://img.shields.io/npm/v/modpack-lock?style=for-the-badge&logo=npm&logoColor=white&label=npm&color=%23C12127&labelColor=%23505050"></a>
+
+# modpack-lock
+
+###### by nickesc - [GitHub](https://github.com/nickesc) | [Modrinth](https://modrinth.com/user/nickesc)
+
+Creates a modpack lockfile for files hosted on Modrinth (mods, resource packs, shaders and datapacks).
+
+
+## Overview
+
+Many mod and pack authors request that modpack creators link to Modrinth or CurseForge downloads rather than re-hosting files. This makes it difficult to track content files in version control when pushing to a remote server.
+
+This script generates a `modpack.lock` file in the current directory containing a JSON object with a plaintext representation of the modpack's contents. This object contains the metadata for the content available on Modrinth, including hashes, versions, names, download URLs and more. This allows for easy diffing and clear version history.
+
+> While an `.mrpack` file could be used to track changes to the modpack, it is a large, binary file that cannot be diffed and can contain large amounts of duplicate data from the rest of the repository.
+
+The lockfile could also serve as a basis for restoring modpack contents after cloning the repository to a new machine.
+
+## Installation
+
+To install the script globally with `npm`:
+
+```bash
+npm install -g modpack-lock
+```
+
+Alternatively, you can run it using `npx`:
+
+```bash
+npx modpack-lock
+```
+
+## Usage
+
+Navigate to your Minecraft profile directory (the folder containing `mods`, `resourcepacks`, `datapacks`, and `shaderpacks` folders) and run:
+
+```bash
+modpack-lock
+```
+
+The script will:
+
+1. Scan the `mods`, `resourcepacks`, `datapacks`, and `shaderpacks` directories for `.jar` and `.zip` files
+2. Calculate SHA1 hashes for each file
+3. Query the Modrinth API to find version information
+4. Generate a `modpack.lock` file in the current directory
+
+Then, commit the `modpack.lock` file to your repository and push it to your remote.
+
+> [!TIP]
+> You can run this script as a pre-commit hook to ensure that the modpack lockfile is up to date before committing your changes to your repository.
+>
+> Also, consider adding these rules to your `.gitignore` to ensure you don't commit the modpack contents to your repository, with exceptions for any files that are not Modrinth-hosted:
+>
+> ```txt
+> mods/*.jar
+> resourcepacks/*.zip
+> datapacks/*.zip
+> shaderpacks/*.zip
+> 
+> ## Exceptions
+> # !mods/example.jar
+> ```
+
+## Output
+
+The `modpack.lock` file has the following structure:
+
+```json
+{
+  "version": "1.0.0",
+  "generated": "2026-01-06T03:00:00.000Z",
+  "dependencies": {
+    "mods": [
+      {
+        "path": "mods/example-mod.jar",
+        "version": { ... }
+      }
+    ],
+    "resourcepacks": [ ... ],
+    "datapacks": [ ... ],
+    "shaderpacks": [ ... ]
+  }
+}
+```
+
+## Future Plans
+
+- [ ] Add support for CurseForge
+- [ ] Add support for restoring modpack contents using the lockfile
+- [ ] Add CLI option for dry-run
+- [ ] Add CLI option for verbose output
+- [ ] Add CLI option for quiet output
+- [ ] Add CLI option for printout of rules to add to .gitignore (the files that are not hosted)
+
+Feel free to submit a pull request working on any of the above, or open an issue for any feature requests or bug reports.
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for more details.

package/index.js

@@ -0,0 +1,213 @@
+#!/usr/bin/env node
+
+import fs from 'fs/promises';
+import crypto from 'crypto';
+import path from 'path';
+
+const LOCKFILE_VERSION = '1.0.0';
+const MODPACK_LOCKFILE_NAME = 'modpack.lock';
+const MODRINTH_API_BASE = 'https://api.modrinth.com/v2';
+const MODRINTH_VERSION_FILES_ENDPOINT = `${MODRINTH_API_BASE}/version_files`;
+
+// Get the workspace root from the current working directory
+const WORKSPACE_ROOT = process.cwd();
+
+const DIRECTORIES_TO_SCAN = [
+  { name: 'mods', path: path.join(WORKSPACE_ROOT, 'mods') },
+  { name: 'resourcepacks', path: path.join(WORKSPACE_ROOT, 'resourcepacks') },
+  { name: 'datapacks', path: path.join(WORKSPACE_ROOT, 'datapacks') },
+  { name: 'shaderpacks', path: path.join(WORKSPACE_ROOT, 'shaderpacks') },
+];
+
+/**
+ * Calculate SHA1 hash of a file
+ */
+async function calculateSHA1(filePath) {
+  const fileBuffer = await fs.readFile(filePath);
+  return crypto.createHash('sha1').update(fileBuffer).digest('hex');
+}
+
+/**
+ * Find all files in a directory
+ */
+async function findFiles(dirPath) {
+  const files = [];
+
+  try {
+    const entries = await fs.readdir(dirPath, { withFileTypes: true });
+
+    for (const entry of entries) {
+      if (entry.isFile() && (entry.name.endsWith('.jar') || entry.name.endsWith('.zip'))) {
+        const fullPath = path.join(dirPath, entry.name);
+        files.push(fullPath);
+      }
+    }
+  } catch (error) {
+    // Directory doesn't exist or can't be read - skip it
+    if (error.code !== 'ENOENT') {
+      console.warn(`Warning: Could not read directory ${dirPath}: ${error.message}`);
+    }
+  }
+
+  return files;
+}
+
+/**
+ * Scan a directory and return file info with hashes
+ */
+async function scanDirectory(dirInfo) {
+  const files = await findFiles(dirInfo.path);
+  const fileEntries = [];
+
+  for (const filePath of files) {
+    try {
+      const hash = await calculateSHA1(filePath);
+      const relativePath = path.relative(WORKSPACE_ROOT, filePath);
+
+      fileEntries.push({
+        path: relativePath,
+        fullPath: filePath,
+        hash: hash,
+        category: dirInfo.name,
+      });
+    } catch (error) {
+      console.warn(`Warning: Could not hash file ${filePath}: ${error.message}`);
+    }
+  }
+
+  return fileEntries;
+}
+
+/**
+ * Query Modrinth API for version information from hashes
+ */
+async function getVersionsFromHashes(hashes) {
+  if (hashes.length === 0) {
+    return {};
+  }
+
+  try {
+    const response = await fetch(MODRINTH_VERSION_FILES_ENDPOINT, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+      },
+      body: JSON.stringify({
+        hashes: hashes,
+        algorithm: 'sha1',
+      }),
+    });
+
+    if (!response.ok) {
+      const errorText = await response.text();
+      throw new Error(`Modrinth API error (${response.status}): ${errorText}`);
+    }
+
+    return await response.json();
+  } catch (error) {
+    console.error(`Error querying Modrinth API: ${error.message}`);
+    throw error;
+  }
+}
+
+
+/**
+ * Create empty lockfile structure
+ */
+function createEmptyLockfile() {
+  return {
+    version: LOCKFILE_VERSION,
+    generated: new Date().toISOString(),
+    dependencies: {},
+  };
+}
+
+/**
+ * Create lockfile structure from file info and version data
+ */
+function createLockfile(fileEntries, versionData) {
+  const lockfile = createEmptyLockfile();
+
+  // Organize by category
+  for (const fileInfo of fileEntries) {
+    const version = versionData[fileInfo.hash];
+
+    lockfile.dependencies[fileInfo.category] ||= [];
+
+    const entry = {
+      path: fileInfo.path,
+      version: version || null,
+    };
+
+    if (!version) {
+      console.warn(`Warning: File ${fileInfo.path} not found on Modrinth`);
+    }
+
+    lockfile.dependencies[fileInfo.category].push(entry);
+  }
+
+  return lockfile;
+}
+
+/**
+ * Write lockfile to disk
+ */
+async function writeLockfile(lockfile, outputPath) {
+  const content = JSON.stringify(lockfile, null, 2);
+  await fs.writeFile(outputPath, content, 'utf-8');
+  console.log(`Lockfile written to: ${outputPath}`);
+}
+
+/**
+ * Main execution function
+ */
+async function main() {
+  console.log('Scanning directories for modpack files...');
+
+  // Scan all directories
+  const allFileEntries = [];
+  for (const dirInfo of DIRECTORIES_TO_SCAN) {
+    console.log(`Scanning ${dirInfo.name}...`);
+    const fileEntries = await scanDirectory(dirInfo);
+    console.log(`  Found ${fileEntries.length} file(s)`);
+    allFileEntries.push(...fileEntries);
+  }
+
+  if (allFileEntries.length === 0) {
+    console.log('No files found. Creating empty lockfile.');
+    const outputPath = path.join(WORKSPACE_ROOT, MODPACK_LOCKFILE_NAME);
+    await writeLockfile(createEmptyLockfile(), outputPath);
+    return;
+  }
+
+  console.log(`\nTotal files found: ${allFileEntries.length}`);
+  console.log('\nQuerying Modrinth API...');
+
+  // Extract all hashes
+  const hashes = allFileEntries.map(info => info.hash);
+
+  // Query Modrinth API
+  const versionData = await getVersionsFromHashes(hashes);
+
+  console.log(`\nFound version information for ${Object.keys(versionData).length} out of ${hashes.length} files`);
+
+  // Create lockfile
+  const lockfile = createLockfile(allFileEntries, versionData);
+
+  // Write lockfile
+  const outputPath = path.join(WORKSPACE_ROOT, MODPACK_LOCKFILE_NAME);
+  await writeLockfile(lockfile, outputPath);
+
+  // Summary
+  console.log('\n=== Summary ===');
+  for (const [category, entries] of Object.entries(lockfile.dependencies)) {
+    const withVersion = entries.filter(e => e.version !== null).length;
+    const withoutVersion = entries.length - withVersion;
+    console.log(`${category}: ${entries.length} file(s) (${withVersion} found on Modrinth, ${withoutVersion} unknown)`);
+  }
+}
+
+main().catch(error => {
+  console.error('Error:', error);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "modpack-lock",
+  "version": "0.1.0",
+  "description": "Create a modpack lockfile for files hosted on Modrinth (mods, resource packs, shaders and datapacks)",
+  "homepage": "https://github.com/nickesc/modpack-lock#readme",
+  "bugs": {
+    "url": "https://github.com/nickesc/modpack-lock/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nickesc/modpack-lock.git"
+  },
+  "license": "MIT",
+  "author": "N. Escobar <nick@nescobar.media> (https://nickesc.github.io/)",
+  "type": "module",
+  "main": "index.js",
+  "bin": {
+    "modpack-lock": "index.js"
+  },
+  "keywords": [
+    "modrinth",
+    "minecraft",
+    "modpack",
+    "lockfile"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "scripts": {
+    "test": "node index.js",
+    "start": "node index.js"
+  },
+  "files": [
+    "index.js",
+    "README.md",
+    "LICENSE",
+    "package.json"
+  ]
+}