@effectstream/npm-midnight-indexer 0.3.99

package/README.md

@@ -0,0 +1,245 @@
+# Midnight Indexer
+
+A Node.js package that downloads and runs the
+[Midnight](https://midnight.network) Indexer. The indexer requires a running
+Midnight Node to function properly.
+
+## Overview
+
+This package provides flexible execution options for the Midnight Indexer:
+
+- **Docker mode**: Runs the indexer in a Docker container (recommended)
+- **Binary mode**: Downloads and runs the native binary locally (Linux, Windows,
+  macOS arm64)
+
+### Platform Support
+
+| Platform | Docker | Binary |
+| -------- | ------ | ------ |
+| macOS    | ✅ Yes | ✅ Yes |
+| Linux    | ✅ Yes | ✅ Yes |
+| Windows  | ❌ No  | ✅ Yes |
+
+## Installation
+
+```bash
+npm install npm-midnight-indexer
+```
+
+## Prerequisites
+
+### For Docker Mode
+
+- Docker installed and running
+- `APP__INFRA__SECRET` environment variable (required)
+
+### For Binary Mode
+
+- Supported platform (Linux/macOS ARM64)
+- Local Midnight Node and Proof Server running on standard ports. But they can
+  be set using env variables
+- `APP__INFRA__SECRET` environment variable (required)
+
+## Usage
+
+### Command Line Options
+
+```bash
+node index.js [options] [args...]
+```
+
+**Options:**
+
+- `--docker` - Force Docker execution
+- `--binary` - Force binary execution (available on Linux, Windows, macOS arm64)
+- `--help` - Show help information
+
+**Examples:**
+
+```bash
+# Force Docker usage
+APP__INFRA__SECRET=mysecret node index.js --docker
+
+# Force binary usage (Linux/Windows/macOS arm64)
+APP__INFRA__SECRET=mysecret node index.js --binary
+
+# Interactive mode - prompts for Docker vs binary choice
+APP__INFRA__SECRET=mysecret node index.js
+
+# Show help
+node index.js --help
+```
+
+## Environment Variables
+
+The indexer supports several environment variables with different defaults based
+on execution mode:
+
+| Variable                        | Required | Docker Default             | Binary Default          | Description                    |
+| ------------------------------- | -------- | -------------------------- | ----------------------- | ------------------------------ |
+| `APP__INFRA__SECRET`            | Yes      | -                          | -                       | Secret key for the application |
+| `LEDGER_NETWORK_ID`             | No       | `Undeployed`               | `Undeployed`            | Ledger network identifier      |
+| `SUBSTRATE_NODE_WS_URL`         | No       | `ws://node:9944`           | `ws://localhost:9944`   | Substrate node WebSocket URL   |
+| `FEATURES_WALLET_ENABLED`       | No       | `true`                     | `true`                  | Enable wallet features         |
+| `APP__INFRA__PROOF_SERVER__URL` | No       | `http://proof-server:6300` | `http://localhost:6300` | Proof server URL               |
+| `APP__INFRA__NODE__URL`         | No       | `ws://node:9944`           | `ws://localhost:9944`   | Node WebSocket URL             |
+
+### Environment Variable Examples
+
+```bash
+# Minimal Docker setup
+APP__INFRA__SECRET=A5F07FCAC914A181EC0998CCCA68312DA5F07FCAC914A181EC0998CCCA68312D \
+node index.js --docker
+
+# Custom configuration
+APP__INFRA__SECRET=mysecret \
+LEDGER_NETWORK_ID=CustomNetwork \
+SUBSTRATE_NODE_WS_URL=ws://localhost:9944 \
+APP__INFRA__PROOF_SERVER__URL=http://localhost:6300 \
+node index.js --docker
+
+# Binary mode (uses localhost defaults automatically)
+APP__INFRA__SECRET=mysecret node index.js --binary
+```
+
+## Docker Mode Details
+
+When using Docker mode, the indexer:
+
+1. **Pulls the latest image**: `midnightntwrk/indexer-standalone`
+2. **Maps port 8088**: Container port 8088 → Host port 8088
+3. **Uses container networking**: Defaults work with Docker Compose setups
+4. **Auto-cleanup**: Removes existing containers before starting new ones
+
+### Docker Command Generated
+
+The package generates Docker commands similar to:
+
+```bash
+docker run --rm --name midnight-local-indexer \
+  -p 8088:8088 \
+  -e LEDGER_NETWORK_ID=Undeployed \
+  -e SUBSTRATE_NODE_WS_URL=ws://node:9944 \
+  -e APP__INFRA__SECRET=A5F07FCAC914A181EC0998CCCA68312DA5F07FCAC914A181EC0998CCCA68312D \
+  -e FEATURES_WALLET_ENABLED=true \
+  -e APP__INFRA__PROOF_SERVER__URL=http://proof-server:6300 \
+  -e APP__INFRA__NODE__URL=ws://node:9944 \
+  midnightntwrk/indexer-standalone
+```
+
+## Binary Mode Details
+
+When using binary mode, the indexer:
+
+1. **Downloads platform-specific binary** if not already present
+2. **Uses localhost URLs** for all service connections
+3. **Runs natively** on the host system
+
+## Path Resolution
+
+The indexer relies on two user-supplied file paths and **both are interpreted
+relative to the process’s current working directory (CWD)** when they are not
+absolute:
+
+| Configuration location             | Purpose                                      | If relative, resolved against                                             |
+| ---------------------------------- | -------------------------------------------- | ------------------------------------------------------------------------- |
+| `CONFIG_FILE` environment variable | Location of the YAML config file             | The directory you launch `node index.js …` from (or the Docker `WORKDIR`) |
+| `infra.storage.cnn_url` in YAML    | SQLite database used by the standalone build | The CWD at runtime of the indexer process                                 |
+
+### Practical tips
+
+1. Prefer absolute paths when you need to be explicit.
+2. In **binary mode** this package sets the CWD to the bundled
+   `indexer-standalone` folder, so a default `cnn_url: "./indexer.sqlite"` ends
+   up next to the binary.
+3. In **Docker mode** the image’s `WORKDIR` is `/opt/indexer-standalone`.
+   Bind-mount volumes accordingly if you want the database file somewhere else.
+
+---
+
+### Supported Binary Platforms
+
+- Linux ARM64 (`linux-arm64`)
+- Linux AMD64 (`linux-amd64`)
+- macOS ARM64 (`macos-arm64`)
+
+## Troubleshooting
+
+### Common Issues
+
+**"Docker is not installed or not available"**
+
+- Install Docker Desktop or Docker Engine
+- Ensure Docker is running
+- Check Docker is accessible from command line: `docker --version`
+
+**"APP__INFRA__SECRET environment variable is required"**
+
+- Set the secret: `export APP__INFRA__SECRET=your_secret_here`
+- Or pass inline: `APP__INFRA__SECRET=your_secret node index.js --docker`
+- Required for both Docker and binary execution modes
+
+**"Binary execution is only supported on macOS ARM64"**
+
+- Use `--docker` flag or run without flags to use Docker automatically
+- Install Docker if not already installed
+
+**"Failed to start midnight-indexer"**
+
+- Check if ports 8088, 6300, 9944 are available
+- Verify Midnight Node is running and accessible
+- Check environment variables are correctly set
+
+### Logs and Debugging
+
+The indexer outputs detailed logs including:
+
+- Download progress for binaries
+- Docker pull progress
+- Process IDs and status
+- Error messages with suggestions
+
+## Development
+
+### Package Structure
+
+```
+npm-midnight-indexer/
+├── index.js              # Main entry point
+├── binary.js             # Binary download logic
+├── docker.js             # Docker execution logic
+├── run_midnight_indexer.js # Binary execution logic
+├── package.json          # Package configuration
+└── README.md            # This file
+```
+
+### Testing
+
+```bash
+# Test Docker detection
+node -e "const { checkIfDockerExists } = require('./docker.js'); checkIfDockerExists().then(console.log)"
+
+# Test help
+node index.js --help
+
+# Test platform detection
+node -e "console.log('Platform:', require('os').platform())"
+```
+
+## License
+
+ISC
+
+## Support
+
+For issues related to:
+
+- **This package**: Open an issue in the repository
+- **Midnight Protocol**: Visit [midnight.network](https://midnight.network)
+- **Docker**: Check [Docker documentation](https://docs.docker.com/)
+
+## Related Links
+
+- [Midnight Network](https://midnight.network)
+- [Docker Hub - Midnight Indexer](https://hub.docker.com/r/midnightntwrk/indexer-standalone)
+- [Node.js](https://nodejs.org/)

package/binary.js

@@ -0,0 +1,102 @@
+const os = require("os");
+const fs = require("fs");
+const axios = require("axios");
+const extract = require("extract-zip");
+const path = require("path");
+
+const CURRENT_BINARY_VERSION = "v2.1.4";
+
+/*
+@returns {string} The platform and architecture of the current machine. Example: "linux-amd64"
+*/
+function getPlatform() {
+  const platform = os.platform();
+  const arch = os.arch();
+
+  if (platform === "darwin") {
+    // For macOS, return the full platform-arch combination
+    if (arch === "x64") {
+      return "macos-amd64"; // Will not be in supportedPlatforms, so will fall back to Docker
+    } else {
+      return `macos-${arch}`;
+    }
+  } else {
+    // For Linux and other platforms, only arch is needed
+    if (arch === "x64") {
+      return `${platform}-amd64`;
+    }
+    return `${platform}-${arch}`;
+  }
+}
+
+/*
+@returns {string} The URL to download the binary for the current platform.
+*/
+function getBinaryUrl() {
+  const platform = getPlatform();
+  const supportedPlatforms = require("./package.json").supportedPlatforms;
+  // Check if platform is supported
+  if (!supportedPlatforms.includes(platform)) {
+    throw new Error(`Unsupported platform: ${platform}`);
+  }
+  return `https://paima-midnight.nyc3.cdn.digitaloceanspaces.com/binaries/indexer-standalone-${platform}-${CURRENT_BINARY_VERSION}.zip`;
+}
+
+/*
+@returns {Promise<void>} Downloads and saves the binary for the current platform.
+*/
+async function downloadAndSaveBinary() {
+  const url = getBinaryUrl();
+  try {
+    console.error(`Downloading... ${url}`);
+    const response = await axios.get(url, { responseType: "stream" });
+    const writer = fs.createWriteStream(
+      path.join(__dirname, "indexer-standalone.zip"),
+    );
+
+    response.data.pipe(writer);
+
+    return new Promise((resolve, reject) => {
+      writer.on("finish", resolve);
+      writer.on("error", reject);
+    });
+  } catch (error) {
+    console.error("Error downloading binary:", error);
+    throw error;
+  }
+}
+
+/*
+@returns {Promise<void>} Unzips the binary for the current platform.
+*/
+async function unzipBinary() {
+  const dir = path.join(__dirname, "indexer-standalone");
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+  await extract(path.join(__dirname, "indexer-standalone.zip"), { dir });
+  fs.unlinkSync(path.join(__dirname, "indexer-standalone.zip"));
+
+  const platform = getPlatform();
+  const parts = platform.split("-");
+  if (parts[0] === "linux") {
+    fs.chmodSync(
+      path.join(
+        __dirname,
+        "indexer-standalone",
+        `indexer-standalone-${platform}`,
+      ),
+      0o755,
+    );
+  }
+}
+
+async function binary() {
+  await downloadAndSaveBinary();
+  await unzipBinary();
+}
+
+module.exports = {
+  binary,
+  getPlatform,
+};

package/docker.js

@@ -0,0 +1,164 @@
+const { spawn, exec } = require('child_process');
+const { promisify } = require('util');
+const execAsync = promisify(exec);
+
+/**
+ * Checks if Docker is installed and available on the system
+ * @returns {Promise<boolean>} True if Docker is available, false otherwise
+ */
+async function checkIfDockerExists() {
+    try {
+        await execAsync('docker --version');
+        return true;
+    } catch (error) {
+        return false;
+    }
+}
+
+/**
+ * Pulls the latest midnight indexer Docker image
+ * @returns {Promise<void>}
+ */
+async function pullDockerImage() {
+    const imageName = 'midnightntwrk/indexer-standalone';
+    
+    console.log(`Pulling Docker image: ${imageName}`);
+    
+    return new Promise((resolve, reject) => {
+        const childProcess = spawn('docker', ['pull', imageName], {
+            stdio: 'inherit'
+        });
+        
+        childProcess.on('exit', (code) => {
+            if (code === 0) {
+                console.log('Docker image pulled successfully');
+                resolve();
+            } else {
+                reject(new Error(`Docker pull failed with exit code ${code}`));
+            }
+        });
+        
+        childProcess.on('error', (error) => {
+            reject(new Error(`Failed to pull Docker image: ${error.message}`));
+        });
+    });
+}
+
+/**
+ * Runs the midnight indexer Docker container
+ * @param {Object} env - Environment variables to pass to the container
+ * @param {Array} args - Arguments to pass to the container
+ * @returns {ChildProcess} The spawned Docker process
+ */
+function runDockerContainer(env = process.env, args = []) {
+    const imageName = 'midnightntwrk/indexer-standalone';
+    const containerName = 'midnight-local-indexer';
+    
+    // Stop and remove existing container if it exists
+    try {
+        require('child_process').execSync(`docker stop ${containerName} 2>/dev/null || true`, { stdio: 'ignore' });
+        require('child_process').execSync(`docker rm ${containerName} 2>/dev/null || true`, { stdio: 'ignore' });
+    } catch (error) {
+        // Ignore errors - container might not exist
+    }
+    
+    // Build Docker run command arguments
+    const dockerArgs = ['run'];
+    
+    // Add container name (remove existing container if it exists)
+    dockerArgs.push('--rm'); // Automatically remove container when it exits
+    dockerArgs.push('--name', containerName);
+    
+    // Intelligent port mapping - default to 8088:8088 if not specified
+    const defaultPort = '8088:8088';
+    let portMapping = defaultPort;
+    
+    // Check if port is specified in args
+    const portArgIndex = args.findIndex(arg => arg.includes('--port') || arg.includes('-p'));
+    if (portArgIndex !== -1 && args[portArgIndex + 1]) {
+        const specifiedPort = args[portArgIndex + 1];
+        portMapping = `${specifiedPort}:${specifiedPort}`;
+        // Remove port args from the args array as they're handled by Docker
+        args.splice(portArgIndex, 2);
+    }
+    
+    dockerArgs.push('-p', portMapping);
+    
+    // Add environment variables
+    const requiredEnvVars = [
+        'LEDGER_NETWORK_ID',
+        'SUBSTRATE_NODE_WS_URL', 
+        'APP__INFRA__SECRET',
+        'FEATURES_WALLET_ENABLED',
+        'APP__INFRA__PROOF_SERVER__URL',
+        'APP__INFRA__NODE__URL'
+    ];
+    
+    // Set default values for Docker environment variables (using container network names)
+    const envDefaults = {
+        'LEDGER_NETWORK_ID': env.LEDGER_NETWORK_ID || 'Undeployed',
+        'SUBSTRATE_NODE_WS_URL': env.SUBSTRATE_NODE_WS_URL || 'ws://node:9944',
+        'APP__INFRA__SECRET': env.APP__INFRA__SECRET,
+        'FEATURES_WALLET_ENABLED': env.FEATURES_WALLET_ENABLED || 'true',
+        'APP__INFRA__PROOF_SERVER__URL': env.APP__INFRA__PROOF_SERVER__URL || 'http://proof-server:6300',
+        'APP__INFRA__NODE__URL': env.APP__INFRA__NODE__URL || 'ws://node:9944'
+    };
+    
+    // Validate that SECRET is provided
+    if (!envDefaults['APP__INFRA__SECRET']) {
+        throw new Error('APP__INFRA__SECRET environment variable is required');
+    }
+    
+    // Add environment variables to Docker command
+    Object.entries(envDefaults).forEach(([key, value]) => {
+        if (value) {
+            dockerArgs.push('-e', `${key}=${value}`);
+        }
+    });
+    
+    // Add any additional environment variables from env object
+    Object.entries(env).forEach(([key, value]) => {
+        if (!requiredEnvVars.includes(key) && value) {
+            dockerArgs.push('-e', `${key}=${value}`);
+        }
+    });
+    
+    // Add the image name
+    dockerArgs.push(imageName);
+    
+    // Add any remaining arguments
+    if (args.length > 0) {
+        dockerArgs.push(...args);
+    }
+    
+    console.log(`Starting Docker container: docker ${dockerArgs.join(' ')}`);
+    
+    const childProcess = spawn('docker', dockerArgs, {
+        stdio: 'inherit'
+    });
+    
+    childProcess.on('spawn', () => {
+        console.log(`Docker container started with PID: ${childProcess.pid}`);
+        console.log(`Container accessible on port: ${portMapping.split(':')[0]}`);
+    });
+    
+    childProcess.on('error', (error) => {
+        console.error('Failed to start Docker container:', error);
+    });
+    
+    childProcess.on('exit', (code, signal) => {
+        if (code !== null) {
+            console.log(`Docker container exited with code: ${code}`);
+        } else {
+            console.log(`Docker container terminated by signal: ${signal}`);
+        }
+    });
+    
+    return childProcess;
+}
+
+module.exports = {
+    checkIfDockerExists,
+    pullDockerImage,
+    runDockerContainer
+};

package/index.js

@@ -0,0 +1,316 @@
+const { binary, getPlatform } = require("./binary");
+const { runMidnightIndexer } = require("./run_midnight_indexer");
+const { checkIfDockerExists, pullDockerImage, runDockerContainer } = require(
+  "./docker",
+);
+const fs = require("fs");
+const path = require("path");
+const readline = require("readline");
+const os = require("os");
+
+function checkIfBinaryExists() {
+  const platform = getPlatform();
+  const parts = platform.split("-");
+  const binaryName = `indexer-standalone-${platform}`;
+  return fs.existsSync(
+    path.join(__dirname, "indexer-standalone", binaryName),
+  );
+}
+
+/**
+ * Checks if the current platform supports binary execution
+ * @returns {boolean} True if binary execution is supported
+ */
+function isBinarySupported() {
+  const platform = os.platform();
+  const arch = os.arch();
+
+  // Check if the current platform-arch combination is supported
+  const supportedPlatforms = require("./package.json").supportedPlatforms;
+
+  let platformString;
+  if (platform === "darwin") {
+    platformString = arch === "x64" ? "macos-amd64" : `macos-${arch}`;
+  } else {
+    platformString = arch === "x64"
+      ? `${platform}-amd64`
+      : `${platform}-${arch}`;
+  }
+
+  return supportedPlatforms.includes(platformString);
+}
+
+/**
+ * Prompts the user to choose between Docker and binary execution
+ * @returns {Promise<boolean>} True if user chooses Docker, false for binary
+ */
+function promptUserForDockerChoice() {
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout,
+  });
+
+  return new Promise((resolve) => {
+    rl.question(
+      "Docker is available. Would you like to use Docker instead of downloading the binary? (y/n): ",
+      (answer) => {
+        rl.close();
+        resolve(answer.toLowerCase() === "y" || answer.toLowerCase() === "yes");
+      },
+    );
+  });
+}
+
+/**
+ * Shows usage information
+ */
+function showUsage() {
+  console.log(`
+Usage: node index.js [options] [args...]
+
+Options:
+  --docker    Force use of Docker container
+  --binary    Force use of binary execution (supports Linux and macOS arm64)
+  --help      Show this help message
+
+Environment Variables:
+  APP__INFRA__SECRET             Required: Secret key for the application
+  LEDGER_NETWORK_ID              Optional: Ledger network ID (default: Undeployed)
+  SUBSTRATE_NODE_WS_URL          Optional: Substrate node WebSocket URL
+                                 (Docker default: ws://node:9944, Binary default: ws://localhost:9944)
+  FEATURES_WALLET_ENABLED        Optional: Enable wallet features (default: true)
+  APP__INFRA__PROOF_SERVER__URL  Optional: Proof server URL
+                                 (Docker default: http://proof-server:6300, Binary default: http://localhost:6300)
+  APP__INFRA__NODE__URL          Optional: Node URL
+                                 (Docker default: ws://node:9944, Binary default: ws://localhost:9944)
+
+Note: macOS Intel users will automatically use Docker. macOS arm64 supports both binary and Docker execution.
+
+Examples:
+  APP__INFRA__SECRET=mysecret node index.js --docker    # Use Docker
+  APP__INFRA__SECRET=mysecret node index.js --binary    # Use binary (if supported)
+  APP__INFRA__SECRET=mysecret node index.js             # Interactive mode (or auto-Docker on unsupported platforms)
+  node index.js --help                                  # Show this help
+`);
+}
+
+/**
+ * Parses command line arguments to extract flags and remaining args
+ * @param {Array} args - Command line arguments
+ * @returns {Object} Object containing useDocker, useBinary flags and remaining args
+ */
+function parseFlags(args) {
+  const flags = {
+    useDocker: false,
+    useBinary: false,
+    showHelp: false,
+    remainingArgs: [],
+  };
+
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === "--docker") {
+      flags.useDocker = true;
+    } else if (args[i] === "--binary") {
+      flags.useBinary = true;
+    } else if (args[i] === "--help" || args[i] === "-h") {
+      flags.showHelp = true;
+    } else {
+      flags.remainingArgs.push(args[i]);
+    }
+  }
+
+  return flags;
+}
+
+async function runWithDocker(env, args) {
+  console.log("Using Docker to run midnight indexer...");
+
+  try {
+    // Pull the latest image
+    await pullDockerImage();
+
+    // Run the container
+    return runDockerContainer(env, args);
+  } catch (error) {
+    console.error("Failed to run with Docker:", error.message);
+    console.log("Falling back to binary execution...");
+    return runWithBinary(env, args);
+  }
+}
+
+/**
+ * Sets appropriate defaults for binary execution (localhost-based)
+ * @param {Object} env - Original environment variables
+ * @returns {Object} Environment variables with localhost defaults
+ */
+function setBinaryDefaults(env) {
+  const binaryEnv = { ...env };
+
+  // Set localhost-based defaults for binary execution
+  if (!binaryEnv.LEDGER_NETWORK_ID) {
+    binaryEnv.LEDGER_NETWORK_ID = "Undeployed";
+  }
+  if (!binaryEnv.SUBSTRATE_NODE_WS_URL) {
+    binaryEnv.SUBSTRATE_NODE_WS_URL = "ws://localhost:9944";
+  }
+  if (!binaryEnv.FEATURES_WALLET_ENABLED) {
+    binaryEnv.FEATURES_WALLET_ENABLED = "true";
+  }
+  if (!binaryEnv.APP__INFRA__PROOF_SERVER__URL) {
+    binaryEnv.APP__INFRA__PROOF_SERVER__URL = "http://localhost:6300";
+  }
+  if (!binaryEnv.APP__INFRA__NODE__URL) {
+    binaryEnv.APP__INFRA__NODE__URL = "ws://localhost:9944";
+  }
+
+  return binaryEnv;
+}
+
+async function runWithBinary(env, args) {
+  console.log("Using binary to run midnight indexer...");
+
+  // Check for required environment variable
+  if (!env.APP__INFRA__SECRET) {
+    console.error("Error: APP__INFRA__SECRET environment variable is required");
+    console.log("Please set APP__INFRA__SECRET=<your_secret> and run again");
+    process.exit(1);
+  }
+
+  if (!checkIfBinaryExists()) {
+    console.log("Binary not found, downloading...");
+    await binary();
+  }
+
+  // Set appropriate localhost defaults for binary execution
+  const binaryEnv = setBinaryDefaults(env);
+
+  return runMidnightIndexer(binaryEnv, args);
+}
+
+async function main(args) {
+  const flags = parseFlags(args);
+  const env = process.env;
+
+  // Show help if requested
+  if (flags.showHelp) {
+    showUsage();
+    process.exit(0);
+  }
+
+  // If both flags are provided, show error
+  if (flags.useDocker && flags.useBinary) {
+    console.error(
+      "Error: Cannot use both --docker and --binary flags simultaneously",
+    );
+    process.exit(1);
+  }
+
+  // If --docker flag is explicitly provided
+  if (flags.useDocker) {
+    const dockerAvailable = await checkIfDockerExists();
+    if (!dockerAvailable) {
+      console.error("Error: Docker is not installed or not available");
+      console.log("Please install Docker or use the --binary flag");
+      process.exit(1);
+    }
+
+    // Check for required environment variable
+    if (!env.APP__INFRA__SECRET) {
+      console.error(
+        "Error: APP__INFRA__SECRET environment variable is required",
+      );
+      console.log(
+        "Please set APP__INFRA__SECRET=<your_secret> when running with --docker",
+      );
+      process.exit(1);
+    }
+
+    return runWithDocker(env, flags.remainingArgs);
+  }
+
+  // If --binary flag is explicitly provided
+  if (flags.useBinary) {
+    if (!isBinarySupported()) {
+      console.error(
+        "Error: Binary execution is not supported on this platform for: " +
+          os.platform() +
+          " " +
+          os.arch(),
+      );
+      console.log(
+        "Please use --docker flag instead, or run without flags to use Docker automatically",
+      );
+      process.exit(1);
+    }
+    return runWithBinary(env, flags.remainingArgs);
+  }
+
+  // No explicit flag provided - determine best execution method
+  const dockerAvailable = await checkIfDockerExists();
+  const binarySupported = isBinarySupported();
+
+  // If binary is not supported on this platform, try Docker
+  if (!binarySupported) {
+    if (!dockerAvailable) {
+      console.error(
+        "Error: Binary execution is not supported on this platform and Docker is not installed or available. For: " +
+          os.platform() +
+          " " +
+          os.arch(),
+      );
+      console.log(
+        "Please install Docker or ensure your platform is supported for binary execution",
+      );
+      process.exit(1);
+    }
+    console.log(
+      "Binary execution not supported on this platform - using Docker",
+    );
+
+    // Check for required environment variable
+    if (!env.APP__INFRA__SECRET) {
+      console.error(
+        "Error: APP__INFRA__SECRET environment variable is required",
+      );
+      console.log("Please set APP__INFRA__SECRET=<your_secret> and run again");
+      process.exit(1);
+    }
+
+    return runWithDocker(env, flags.remainingArgs);
+  }
+
+  // On supported platforms, prompt user if Docker is available
+  if (dockerAvailable) {
+    const useDocker = await promptUserForDockerChoice();
+    if (useDocker) {
+      // Check for required environment variable
+      if (!env.APP__INFRA__SECRET) {
+        console.error(
+          "Error: APP__INFRA__SECRET environment variable is required",
+        );
+        console.log(
+          "Please set APP__INFRA__SECRET=<your_secret> and run again",
+        );
+        process.exit(1);
+      }
+      return runWithDocker(env, flags.remainingArgs);
+    }
+  }
+
+  // Default to binary execution (only on supported platforms)
+  return runWithBinary(env, flags.remainingArgs);
+}
+
+// Handle unhandled promise rejections
+process.on("unhandledRejection", (error) => {
+  console.error("Unhandled promise rejection:", error);
+  process.exit(1);
+});
+
+// Handle SIGINT (Ctrl+C) gracefully
+process.on("SIGINT", () => {
+  console.log("\nShutting down gracefully...");
+  process.exit(0);
+});
+
+main(process.argv.slice(2));

package/indexer-standalone/config.yaml

@@ -0,0 +1,44 @@
+run_migrations: true
+network_id: &network_id "Undeployed"
+
+chain_indexer_application:
+  network_id: *network_id
+  blocks_buffer: 60
+  save_zswap_state_after: 1000
+  caught_up_max_distance: 60
+  caught_up_leeway: 30
+
+wallet_indexer_application:
+  network_id: *network_id
+  active_wallets_repeat_delay: "100ms"
+  active_wallets_ttl: "30m"
+  transaction_batch_size: 10
+  # Number of cores by default.
+  # parallelism:
+
+infra:
+  node:
+    url: "ws://localhost:9944"
+    reconnect_max_delay: "10s" # 10ms, 100ms, 1s, 10s
+    reconnect_max_attempts: 30 # Roughly 5m
+
+  storage:
+    cnn_url: "./data/indexer.sqlite"
+
+  api:
+    address: "127.0.0.1"
+    port: 8088
+    request_body_limit: "1MiB"
+    max_complexity: 200
+    max_depth: 15
+    network_id: *network_id
+
+telemetry:
+  tracing:
+    enabled: false
+    service_name: "indexer"
+    otlp_exporter_endpoint: "http://localhost:4317"
+  metrics:
+    enabled: false
+    address: "0.0.0.0"
+    port: 9000

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "@effectstream/npm-midnight-indexer",
+  "version": "0.3.99",
+  "description": "Downloads and runs the Midnight Indexer. It needs a running Midnight Node",
+  "main": "index.js",
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "bin": {
+    "npm-midnight-indexer": "index.js"
+  },
+  "author": "Paima Studios",
+  "license": "ISC",
+  "supportedPlatforms": [
+    "linux-arm64",
+    "linux-amd64",
+    "macos-arm64"
+  ],
+  "dependencies": {
+    "axios": "^1.10.0",
+    "axios-proxy-builder": "^0.1.2",
+    "extract-zip": "^2.0.1",
+    "js-yaml": "^4.1.0"
+  }
+}

package/run_midnight_indexer.js

@@ -0,0 +1,160 @@
+const { spawn } = require("child_process");
+const path = require("path");
+const fs = require("fs");
+const yaml = require("js-yaml");
+const { getPlatform } = require("./binary");
+/**
+ * Resolves the SQLite database path using the midnight-indexer configuration rules
+ * @param {Object} env - Environment variables
+ * @param {string} workingDir - The working directory where the indexer runs
+ * @returns {string|null} The resolved SQLite database path, or null if not found
+ */
+function resolveSqlitePath(env, workingDir) {
+  // First check the APP__INFRA__STORAGE__CNN_URL environment variable
+  const envCnnUrl = env.APP__INFRA__STORAGE__CNN_URL;
+  if (envCnnUrl) {
+    console.log(`Found SQLite path from environment variable: ${envCnnUrl}`);
+    return envCnnUrl;
+  }
+
+  // Determine config file path using the configuration resolution rules
+  let configPath;
+  if (env.CONFIG_FILE) {
+    configPath = path.isAbsolute(env.CONFIG_FILE)
+      ? env.CONFIG_FILE
+      : path.resolve(workingDir, env.CONFIG_FILE);
+  } else {
+    // Fall back to config.yaml in the current working directory
+    configPath = path.join(workingDir, "config.yaml");
+  }
+
+  console.log(`Looking for config file at: ${configPath}`);
+
+  // Check if config file exists
+  if (!fs.existsSync(configPath)) {
+    console.warn(`Config file not found at: ${configPath}`);
+    return null;
+  }
+
+  try {
+    // Parse the YAML config file
+    const configContent = fs.readFileSync(configPath, "utf8");
+    const config = yaml.load(configContent);
+
+    // Extract the cnn_url from infra.storage
+    const cnnUrl = config?.infra?.storage?.cnn_url;
+    if (!cnnUrl) {
+      console.warn("No cnn_url found in config file under infra.storage");
+      return null;
+    }
+
+    console.log(`Found SQLite path from config file: ${cnnUrl}`);
+
+    // If the path is relative, resolve it against the binary working directory (indexer-standalone)
+    if (!path.isAbsolute(cnnUrl)) {
+      const resolvedPath = path.resolve(workingDir, cnnUrl);
+      console.log(`Resolved relative path to: ${resolvedPath}`);
+      return resolvedPath;
+    }
+
+    return cnnUrl;
+  } catch (error) {
+    console.error(`Failed to parse config file: ${error.message}`);
+    return null;
+  }
+}
+
+/**
+ * Handles the --clean flag by deleting the SQLite database file
+ * @param {Object} env - Environment variables
+ * @param {string} workingDir - The working directory where the indexer runs
+ */
+function handleCleanFlag(env, workingDir) {
+  console.log("Processing --clean flag...");
+
+  const sqlitePath = resolveSqlitePath(env, workingDir);
+
+  if (!sqlitePath) {
+    console.warn("Could not resolve SQLite database path. Skipping cleanup.");
+    return;
+  }
+
+  // Handle sqlite:// URLs and extract the file path
+  let filePath = sqlitePath;
+  if (sqlitePath.startsWith("sqlite://")) {
+    filePath = sqlitePath.replace("sqlite://", "");
+  } else if (sqlitePath.startsWith("sqlite:///")) {
+    filePath = sqlitePath.replace("sqlite:///", "/");
+  }
+
+  console.log(`Attempting to clean SQLite database at: ${filePath}`);
+
+  if (fs.existsSync(filePath)) {
+    try {
+      fs.unlinkSync(filePath);
+      console.log(`Successfully deleted SQLite database: ${filePath}`);
+    } catch (error) {
+      console.error(`Failed to delete SQLite database: ${error.message}`);
+    }
+  } else {
+    console.log(
+      `SQLite database does not exist (will be created fresh): ${filePath}`,
+    );
+  }
+}
+
+/**
+ * Executes the midnight-indexer binary as a child process
+ * @param {Object} env - Environment variables to pass to the child process
+ * @param {Array} args - Optional arguments to pass to the binary
+ * @returns {ChildProcess} The spawned child process
+ */
+function runMidnightIndexer(env = process.env, args = []) {
+  const platform = getPlatform();
+  const parts = platform.split("-");
+  const binaryName = `indexer-standalone-${platform}`;
+  const binaryPath = path.join(
+    __dirname,
+    "indexer-standalone",
+    binaryName,
+  );
+  const workingDir = path.join(__dirname, "indexer-standalone");
+
+  // Check for --clean flag and handle it
+  const cleanFlagIndex = args.indexOf("--clean");
+  if (cleanFlagIndex !== -1) {
+    handleCleanFlag(env, workingDir);
+    // Remove the --clean flag from args since the binary doesn't expect it
+    args.splice(cleanFlagIndex, 1);
+  }
+
+  console.log(`Starting midnight-indexer binary at: ${binaryPath}`);
+
+  const childProcess = spawn(binaryPath, args, {
+    env: env,
+    stdio: "inherit", // Inherit stdin, stdout, stderr from parent process
+    cwd: workingDir, // Run from inside the indexer-standalone directory
+  });
+
+  childProcess.on("spawn", () => {
+    console.log(
+      `midnight-indexer process spawned with PID: ${childProcess.pid}`,
+    );
+  });
+
+  childProcess.on("error", (error) => {
+    console.error("Failed to start midnight-indexer:", error);
+  });
+
+  childProcess.on("exit", (code, signal) => {
+    if (code !== null) {
+      console.log(`midnight-indexer process exited with code: ${code}`);
+    } else {
+      console.log(`midnight-indexer process terminated by signal: ${signal}`);
+    }
+  });
+
+  return childProcess;
+}
+
+module.exports = { runMidnightIndexer };