modpack-lock 0.2.0 → 0.3.1

package/README.md

@@ -1,6 +1,6 @@
 <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>
 <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://github.com/nickesc/modpack-lock/actions/workflows/generateLockfile-tests.yml"><img alt="Tests: github.com/nickesc/modpack-lock/actions/workflows/generateLockfile-tests.yml" src="https://img.shields.io/github/actions/workflow/status/nickesc/modpack-lock/generateLockfile-tests.yml?logo=github&label=tests&logoColor=white&style=for-the-badge&labelColor=%23505050"></a>
+<a href="https://github.com/nickesc/modpack-lock/actions/workflows/generateLockfile-tests.yml"><img alt="Tests: github.com/nickesc/modpack-lock/actions/workflows/generateLockfile-tests.yml" src="https://img.shields.io/github/actions/workflow/status/nickesc/modpack-lock/modpack-lock-tests.yml?logo=github&label=tests&logoColor=white&style=for-the-badge&labelColor=%23505050"></a>
 
 # modpack-lock
 
@@ -8,12 +8,11 @@
 
 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.
+This script generates a `modpack.lock` file in the current directory containing 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. An optional `modpack.json` file can also be created to store your modpack's metadata (name, version, modloader, dependencies, etc.) alongside the lockfile. This setup 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.
 
@@ -33,38 +32,88 @@ Alternatively, you can run it using `npx`:
 npx modpack-lock
 ```
 
-## Usage
+## CLI
 
 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
+
+If a `modpack.json` file exists in the directory, the lockfile's dependency list will also be written to it. Run `modpack-lock init` to create this file.
+
+Then, commit the `modpack.lock` (and `modpack.json`) to your repository and push it to your remote.
+
 ```text
-Usage: modpack-lock [options]
+Usage: modpack-lock [options] [command]
 
-Create a modpack lockfile for files hosted on Modrinth (mods, resource packs, shaders and datapacks)
+Creates a modpack lockfile for files hosted on Modrinth (mods, resource packs, shaders and datapacks)
 
 Options:
+  -p, --path <path>  Path to the modpack directory
   -d, --dry-run      Dry-run mode - no files will be written
+
+GENERATION
   -g, --gitignore    Print .gitignore rules for files not hosted on Modrinth
   -r, --readme       Generate README.md files for each category
-  -p, --path <path>  Path to the modpack directory
 
 LOGGING
   -q, --quiet        Quiet mode - only show errors and warnings
   -s, --silent       Silent mode - no output
 
 INFORMATION
-  -V, --version      output the version number
-  --help             display help for modpack-lock
+  -V                 output the version number
+  -h, --help         display help for modpack-lock
+
+Commands:
+  init [options]     This utility will walk you through creating a modpack.json file. It only covers the most common items, and tries to guess sensible defaults.
 ```
 
-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
+### Initialization
+
+To initialize a new modpack, run:
+
+```bash
+modpack-lock init
+```
+
+This will create a `modpack.json` file that stores your modpack's metadata (name, version, author, etc.), including a list of dependency slugs. This file is optional, but when present, the main command will also write the lockfile dependencies to `modpack.json`. It will also regenerate the lockfile.
 
-Then, commit the `modpack.lock` file to your repository and push it to your remote.
+The interactive mode will prompt you for each field. Set their initial values using the available option flags. Use `--noninteractive` with the required options (`--author`, `--modloader`, `--targetMinecraftVersion`) to skip prompts.
+
+```text
+Usage: modpack-lock init [options]
+
+This utility will walk you through creating a modpack.json file. It only covers the most common items, and tries to guess sensible defaults.
+
+Options:
+  -f, --folder <path>                                Path to the modpack directory
+  -n, --noninteractive                               Non-interactive mode - must provide options for required fields
+
+MODPACK INFORMATION
+  --name <name>                                      Modpack name; defaults to the directory name; required
+  --version <version>                                Modpack version; defaults to 1.0.0; required
+  --id <id>                                          Modpack slug/ID; defaults to the directory name slugified; required
+  --description <description>                        Modpack description
+  --author <author>                                  Modpack author; required
+  --projectUrl <projectUrl>                          Modpack URL
+  --sourceUrl <sourceUrl>                            Modpack source code URL
+  --license <license>                                Modpack license
+  --modloader <modloader>                            Modpack modloader; required
+  --targetModloaderVersion <targetModloaderVersion>  Target modloader version
+  --targetMinecraftVersion <targetMinecraftVersion>  Target Minecraft version; required
+
+INFORMATION
+  --help                                             display help for modpack-lock init
+```
 
 > [!TIP]
 >
@@ -82,9 +131,26 @@ Then, commit the `modpack.lock` file to your repository and push it to your remo
 > # !mods/example.jar
 > ```
 
-## Output
+## API
+
+For programmatic usage, `modpack-lock` exports these functions:
+
+- `getModpackInfo()`
+- `getLockfile()`
+- `generateJson()`
+- `generateGitignoreRules()`
+- `generateReadmeFiles()`
+- `generateLockfile()`
+- `generateModpackFiles()`
+- `promptUserForInfo()`
+
+See the [API documentation](https://nickesc.github.io/modpack-lock) for full details.
+
+## File Formats
+
+### `modpack.lock`
 
-The `modpack.lock` file has the following structure:
+The lockfile contains metadata about Modrinth-hosted files found in your modpack directories:
 
 ```json
 {
@@ -111,6 +177,34 @@ The `modpack.lock` file has the following structure:
 }
 ```
 
+### `modpack.json`
+
+If created via `modpack-lock init`, the JSON file combines your modpack metadata with the lockfile's dependency list:
+
+```json
+{
+  "name": "My Modpack",
+  "version": "1.0.0",
+  "id": "my-modpack",
+  "description": "",
+  "author": "name",
+  "projectUrl": "",
+  "sourceUrl": "",
+  "license": "",
+  "modloader": "modloader",
+  "targetModloaderVersion": "",
+  "targetMinecraftVersion": "x.y.z",
+  "dependencies": {
+    "mods": [ ... ],
+    "resourcepacks": [ ... ],
+    "datapacks": [ ... ],
+    "shaderpacks": [ ... ]
+  }
+}
+```
+
 ## License
 
 This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for more details.
+
+<a href="https://github.com/nickesc/modpack-lock/blob/main/LICENSE"><img class="badge-img" alt="GitHub License" src="https://img.shields.io/github/license/nickesc/modpack-lock?style=for-the-badge&labelColor=%23333&color=%230070ff"></a>

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "modpack-lock",
-  "version": "0.2.0",
-  "description": "Create a modpack lockfile for files hosted on Modrinth (mods, resource packs, shaders and datapacks)",
+  "version": "0.3.1",
+  "description": "Creates a modpack lockfile for files hosted on Modrinth (mods, resource packs, shaders and datapacks)",
   "bugs": {
     "url": "https://github.com/nickesc/modpack-lock/issues"
   },
@@ -9,12 +9,13 @@
     "type": "git",
     "url": "git+https://github.com/nickesc/modpack-lock.git"
   },
+  "homepage": "https://nickesc.github.io/modpack-lock",
   "license": "MIT",
   "author": "N. Escobar <nick@nescobar.media> (https://nickesc.github.io/)",
   "type": "module",
-  "main": "src/generate-lockfile.js",
+  "main": "src/modpack-lock.js",
   "bin": {
-    "modpack-lock": "src/modpack-lock.js"
+    "modpack-lock": "src/cli.js"
   },
   "keywords": [
     "modrinth",
@@ -23,23 +24,29 @@
     "lockfile"
   ],
   "engines": {
-    "node": ">=18.0.0"
+    "node": ">=22.0.0"
   },
   "scripts": {
     "test": "vitest --run",
-    "start": "node src/modpack-lock.js",
-    "modpack-lock": "node src/modpack-lock.js"
+    "start": "node src/cli.js",
+    "docs": "typedoc",
+    "modpack-lock": "node src/cli.js"
   },
   "files": [
     "README.md",
     "LICENSE",
     "package.json",
-    "src/*.js"
+    "src/**/*.js"
   ],
   "dependencies": {
-    "commander": "^14.0.2"
+    "commander": "^14.0.2",
+    "prompts": "^2.4.2",
+    "slugify": "^1.6.6"
   },
   "devDependencies": {
+    "@vitest/coverage-v8": "^4.0.16",
+    "typedoc": "^0.28.16",
+    "typedoc-github-theme": "^0.3.1",
     "unzipper": "^0.12.3",
     "vitest": "^4.0.16"
   }

package/src/cli.js

@@ -0,0 +1,166 @@
+#!/usr/bin/env NODE_OPTIONS=--no-warnings node
+
+import { Command } from 'commander';
+import path from 'path';
+import slugify from 'slugify';
+import {generateLockfile} from './generate_lockfile.js';
+import generateJson from './generate_json.js';
+import { generateModpackFiles } from './modpack-lock.js';
+import promptUserForInfo from './modpack_info.js';
+import { getModpackInfo } from './directory_scanning.js';
+import * as config from './config/index.js';
+import pkg from '../package.json' with { type: 'json' };
+
+
+const modpackLock = new Command('modpack-lock');
+
+const originalLogs = {
+    log: console.log,
+    info: console.info,
+    warn: console.warn,
+    error: console.error,
+};
+
+/**
+ * Silence all console.log output
+ */
+function quietConsole(silent = false) {
+    console.log = () => { };
+    console.info = () => { };
+    if (silent) {
+        console.warn = () => { };
+        console.error = () => { };
+    }
+}
+
+/**
+ * Restore the console's original functions
+ */
+function restoreConsole() {
+    console.log = originalLogs.log;
+    console.info = originalLogs.info;
+    console.warn = originalLogs.warn;
+    console.error = originalLogs.error;
+}
+
+modpackLock
+    .name(pkg.name)
+    .description(pkg.description)
+    .summary("Create a modpack lockfile")
+    .optionsGroup("Options:")
+    .option('-p, --path <path>', 'Path to the modpack directory')
+    .option('-d, --dry-run', 'Dry-run mode - no files will be written')
+    .optionsGroup("GENERATION")
+    .option('-g, --gitignore', 'Print .gitignore rules for files not hosted on Modrinth')
+    .option('-r, --readme', 'Generate README.md files for each category')
+    .optionsGroup("LOGGING")
+    .option('-q, --quiet', 'Quiet mode - only show errors and warnings')
+    .option('-s, --silent', 'Silent mode - no output')
+    .optionsGroup("INFORMATION")
+    .helpOption("-h, --help", `display help for ${pkg.name}`)
+    .version(pkg.version, '-V')
+    .action(async (options) => {
+        try {
+            const currDir = options.path || process.cwd();
+
+            if (options.quiet) {
+                quietConsole();
+            } else if (options.silent) {
+                quietConsole(true);
+            }
+
+            const modpackInfo = await getModpackInfo(currDir);
+            if (modpackInfo) {
+                await generateModpackFiles(modpackInfo, currDir, options);
+            } else {
+                await generateLockfile(currDir, options);
+            }
+        } catch (error) {
+            console.error('Error:', error);
+            process.exitCode = 1;
+        }
+    });
+
+const jsonDescription = `This utility will walk you through creating a ${config.MODPACK_JSON_NAME} file. It only covers the most common items, and tries to guess sensible defaults.`;
+
+modpackLock.command('init')
+    .description(jsonDescription)
+    .optionsGroup("Options:")
+    .option('-f, --folder <path>', 'Path to the modpack directory')
+    .option("-n, --noninteractive", 'Non-interactive mode - must provide options for required fields')
+    .optionsGroup("MODPACK INFORMATION")
+    .option('--name <name>', 'Modpack name; defaults to the directory name')
+    .option('--version <version>', 'Modpack version; defaults to 1.0.0')
+    .option('--id <id>', 'Modpack slug/ID; defaults to the directory name slugified')
+    .option('--description <description>', 'Modpack description')
+    .option('--author <author>', 'Modpack author; required')
+    .option('--projectUrl <projectUrl>', 'Modpack URL')
+    .option('--sourceUrl <sourceUrl>', 'Modpack source code URL')
+    .option('--license <license>', 'Modpack license')
+    .option('--modloader <modloader>', 'Modpack modloader; required')
+    .option('--targetModloaderVersion <targetModloaderVersion>', 'Target modloader version')
+    .option('--targetMinecraftVersion <targetMinecraftVersion>', 'Target Minecraft version; required')
+    .optionsGroup("INFORMATION")
+    .helpOption("--help", `display help for ${pkg.name} init`)
+    .action(async (options) => {
+        const currDir = options.folder || process.cwd();
+
+        if (options.noninteractive) {
+            quietConsole();
+            if (!options.author || !options.modloader || !options.targetMinecraftVersion) {
+                console.error('Error: Must provide options for required fields');
+                process.exitCode = 1;
+                return;
+            } else {
+                const name = options.name || path.basename(currDir);
+                const modpackInfo = {
+                    name: name,
+                    version: options.version || '1.0.0',
+                    id: slugify(options.id || name, config.SLUGIFY_OPTIONS),
+                    description: options.description || '',
+                    author: options.author,
+                    projectUrl: options.projectUrl || '',
+                    sourceUrl: options.sourceUrl || '',
+                    license: options.license || '',
+                    modloader: options.modloader,
+                    targetModloaderVersion: options.targetModloaderVersion || '',
+                    targetMinecraftVersion: options.targetMinecraftVersion,
+                };
+                try {
+                    await generateModpackFiles(modpackInfo, currDir, { dryRun: false });
+                } catch (error) {
+                    console.error('Error:', error);
+                    process.exitCode = 1;
+                }
+            }
+        } else {
+            console.log(jsonDescription);
+            console.log("\nSee `modpack-lock init --help` for definitive documentation on these fields and exactly what they do.\n");
+            console.log("Press ^C at any time to quit.\n");
+            try {
+                const modpackInfo = await promptUserForInfo({
+                    name: options.name || path.basename(currDir),
+                    version: options.version,
+                    id: options.id,
+                    description: options.description,
+                    author: options.author,
+                    projectUrl: options.projectUrl,
+                    sourceUrl: options.sourceUrl,
+                    license: options.license,
+                    modloader: options.modloader,
+                    targetModloaderVersion: options.targetModloaderVersion,
+                    targetMinecraftVersion: options.targetMinecraftVersion,
+                });
+
+                await generateModpackFiles(modpackInfo, currDir, { dryRun: false });
+            } catch (error) {
+                console.error('Error:', error);
+                process.exitCode = 1;
+            }
+        }
+    });
+
+modpackLock.parseAsync().catch((error) => {
+    console.error('Error:', error);
+    process.exit(1);
+});

package/src/config/api.js

@@ -0,0 +1,14 @@
+/** Modrinth API base URL */
+export const MODRINTH_API_BASE = 'https://api.modrinth.com/v2';
+
+/** Modrinth version files endpoint */
+export const MODRINTH_VERSION_FILES_ENDPOINT = `${MODRINTH_API_BASE}/version_files`;
+
+/** Modrinth projects endpoint */
+export const MODRINTH_PROJECTS_ENDPOINT = `${MODRINTH_API_BASE}/projects`;
+
+/** Modrinth users endpoint */
+export const MODRINTH_USERS_ENDPOINT = `${MODRINTH_API_BASE}/users`;
+
+/** Batch size for Modrinth API requests */
+export const BATCH_SIZE = 100;

package/src/config/constants.js

@@ -0,0 +1,20 @@
+/** Lockfile format version -- increment on changes to the format */
+export const LOCKFILE_VERSION = "1.0.1";
+
+/** Required fields for the modpack information */
+export const MODPACK_INFO_REQUIRED_FIELDS = [
+    "name",
+    "version",
+    "id",
+    "author",
+    "modloader",
+    "targetMinecraftVersion"
+];
+
+/** Dependency categories, corresponds to folders in Minecraft profile */
+export const DEPENDENCY_CATEGORIES = [
+    "mods",
+    "resourcepacks",
+    "shaderpacks",
+    "datapacks"
+];

package/src/config/files.js

@@ -0,0 +1,5 @@
+/** Machine-readable/lockfile name */
+export const MODPACK_LOCKFILE_NAME = "modpack.lock";
+
+/** Human-readable/JSON file name */
+export const MODPACK_JSON_NAME = "modpack.json";

package/src/config/index.js

@@ -0,0 +1,4 @@
+export * from './constants.js';
+export * from './api.js';
+export * from './files.js';
+export * from './options.js';

package/src/config/options.js

@@ -0,0 +1,2 @@
+/** Options for slugify */
+export const SLUGIFY_OPTIONS = { lower: true, strict: true, separator: '-', locale: 'en', trim: true };

package/src/config/types.js

@@ -0,0 +1,45 @@
+/**
+ * @typedef {Object} ModpackInfo
+ * Contains information about the modpack that is not dependent on the lockfile.
+ * @property {string} name - The name of the modpack (Required)
+ * @property {string} version - The version of the modpack (Required)
+ * @property {string} description - The description of the modpack
+ * @property {string} id - The slug/ID of the modpack (Required)
+ * @property {string} author - The author of the modpack (Required)
+ * @property {string} projectUrl - The project URL of the modpack
+ * @property {string} sourceUrl - The source code URL of the modpack
+ * @property {string} license - The license of the modpack
+ * @property {string} modloader - The modloader of the modpack (Required)
+ * @property {string} targetModloaderVersion - The target modloader version of the modpack
+ * @property {string} targetMinecraftVersion - The target Minecraft version of the modpack (Required)
+ */
+
+/**
+ * @typedef {Object} Lockfile
+ * Contains information about the modpack dependencies and their versions.
+ * @property {string} version - The version of the modpack
+ * @property {string} generated - The date and time the lockfile was generated
+ * @property {number} total - The total number of files in the modpack
+ * @property {Object} counts - The counts object
+ * @property {number} counts.mods - The mods count
+ * @property {number} counts.resourcepacks - The resourcepacks count
+ * @property {number} counts.datapacks - The datapacks count
+ * @property {number} counts.shaderpacks - The shaderpacks count
+ * @property {Object} dependencies - The dependencies object
+ * @property {Array<Object>} dependencies.mods - The mods object
+ * @property {Array<Object>} dependencies.resourcepacks - The resourcepacks object
+ * @property {Array<Object>} dependencies.datapacks - The datapacks object
+ * @property {Array<Object>} dependencies.shaderpacks - The shaderpacks object
+ */
+
+/**
+ * @typedef {Object} Options
+ * Contains options for the generation of the modpack files.
+ * @property {boolean} dryRun - Whether to dry run the generation
+ * @property {boolean} quiet - Whether to quiet the console output
+ * @property {boolean} silent - Whether to silent the console output
+ * @property {boolean} gitignore - Whether to generate a .gitignore file
+ * @property {boolean} readme - Whether to generate README.md files
+ */
+
+export {};

package/src/directory_scanning.js

@@ -0,0 +1,118 @@
+import fs from 'fs/promises';
+import crypto from 'crypto';
+import path from 'path';
+import * as files from './config/files.js';
+import * as constants from './config/constants.js';
+
+/**
+ * @typedef {import('./config/types.js').ModpackInfo} ModpackInfo
+ * @typedef {import('./config/types.js').Lockfile} Lockfile
+ */
+
+/**
+ * Get the directories to scan for modpack files
+ * @param {string} directoryPath - The path to the directory to scan
+ * @returns {Array<Object>} The directories to scan
+ */
+export function getScanDirectories(directoryPath) {
+    const scanDirectories = [];
+    for (const category of constants.DEPENDENCY_CATEGORIES) {
+        scanDirectories.push({ name: category, path: path.join(directoryPath, category) });
+    }
+    return scanDirectories;
+}
+
+/**
+ * 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) {
+        if (error.code !== 'ENOENT') {
+            console.warn(`Warning: Could not read directory ${dirPath}: ${error.message}`);
+        }
+    }
+
+    files.sort((a, b) => a.localeCompare(b, 'en', { numeric: true, sensitivity: 'base' }));
+    return files;
+}
+
+/**
+ * Scan a directory and return file info with hashes
+ */
+export async function scanDirectory(dirInfo, workspaceRoot) {
+    const files = await findFiles(dirInfo.path);
+    const fileEntries = [];
+
+    for (const filePath of files) {
+        try {
+            const hash = await calculateSHA1(filePath);
+            const relativePath = path.relative(workspaceRoot, 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;
+}
+
+/**
+ * Scan for existing JSON file and return the JSON object if it exists
+ */
+async function getJsonFile(directoryPath, filename) {
+    const jsonPath = path.join(directoryPath, filename);
+    // try to read the file
+    try {
+        const fileContent = await fs.readFile(jsonPath, 'utf-8');
+        return JSON.parse(fileContent);
+    } catch (error) {
+        if (error.code !== 'ENOENT') {
+            throw new Error(`Error: Could not read file ${jsonPath}: ${error.message}`);
+        } else {
+            return null;
+        }
+    }
+}
+
+/**
+ * Get the modpack info from the JSON file if it exists
+ * @param {string} directoryPath - The path to the directory to scan
+ * @returns {Promise<ModpackInfo|null>} The modpack info JSON object if the file exists, otherwise null
+ */
+export async function getModpackInfo(directoryPath) {
+    return getJsonFile(directoryPath, files.MODPACK_JSON_NAME);
+}
+
+/**
+ * Get the lockfile file if it exists
+ * @param {string} directoryPath - The path to the directory to scan
+ * @returns {Lockfile|null} The JSON object if the file exists, otherwise null
+ */
+export async function getLockfile(directoryPath) {
+    return getJsonFile(directoryPath, files.MODPACK_LOCKFILE_NAME);
+}