@dotenc/cli 0.1.0

package/dist/package.json

@@ -0,0 +1,47 @@
+{
+    "name": "@dotenc/cli",
+    "version": "0.1.0",
+    "description": "🔐 Secure, encrypted environment variables that live in your codebase",
+    "type": "module",
+    "bin": {
+        "dotenc": "./dist/cli.js"
+    },
+    "files": [
+        "dist"
+    ],
+    "scripts": {
+        "dev": "tsx src/cli.ts",
+        "build": "tsc"
+    },
+    "keywords": [
+        "environment",
+        "variables",
+        "safe",
+        "secure",
+        "codebase",
+        "cli",
+        "command",
+        "line",
+        "tool",
+        "utility",
+        "env",
+        "box",
+        "dotenv",
+        "encrypted",
+        "codebase"
+    ],
+    "author": "Ivan Filho <i@ivanfilho.com>",
+    "license": "MIT",
+    "devDependencies": {
+        "@biomejs/biome": "^1.9.4",
+        "@types/node": "^22.13.7",
+        "tsx": "^4.19.3",
+        "typescript": "^5.8.2"
+    },
+    "dependencies": {
+        "@paralleldrive/cuid2": "^2.2.2",
+        "commander": "^13.1.0",
+        "inquirer": "^12.4.2",
+        "zod": "^3.24.2"
+    }
+}

package/dist/src/cli.js

@@ -0,0 +1,42 @@
+#!/usr/bin/env node
+import { Command, Option } from "commander";
+import pkg from "../package.json" assert { type: "json" };
+import { configCommand } from "./commands/config";
+import { debugCommand } from "./commands/debug";
+import { editCommand } from "./commands/edit";
+import { initCommand } from "./commands/init";
+import { runCommand } from "./commands/run";
+import { tokenExportCommand } from "./commands/token/export";
+import { tokenImportCommand } from "./commands/token/import";
+const program = new Command();
+program.name("dotenc").description(pkg.description).version(pkg.version);
+if (process.env.NODE_ENV !== "production") {
+    program.command("debug").description("Debug the CLI").action(debugCommand);
+}
+program
+    .command("init [environment]")
+    .description("Initialize a new safe environment")
+    .action(initCommand);
+program
+    .command("edit [environment]")
+    .description("Edit an environment")
+    .action(editCommand);
+program
+    .command("run <environment> <command> [args...]")
+    .description("Run a command in an environment")
+    .action(runCommand);
+const token = program.command("token").description("Manage stored tokens");
+token
+    .command("import <environment> <token>")
+    .description("Import a token for an environment")
+    .action(tokenImportCommand);
+token
+    .command("export <environment>")
+    .description("Export a token from an environment")
+    .action(tokenExportCommand);
+program
+    .command("config <key> [value]")
+    .addOption(new Option("-r, --remove", "Remove a configuration key"))
+    .description("Manage global configuration")
+    .action(configCommand);
+program.parse();

package/dist/src/commands/config.js

@@ -0,0 +1,15 @@
+import { getHomeConfig, setHomeConfig } from "../helpers/homeConfig";
+export const configCommand = async (key, value, options) => {
+    const config = await getHomeConfig();
+    if (options.remove) {
+        delete config[key];
+        await setHomeConfig(config);
+        return;
+    }
+    if (value) {
+        config[key] = value;
+        await setHomeConfig(config);
+        return;
+    }
+    console.log(config[key]);
+};

package/dist/src/commands/debug.js

@@ -0,0 +1,16 @@
+import crypto from "node:crypto";
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { decrypt, encrypt } from "../helpers/crypto";
+export const debugCommand = async () => {
+    const token = crypto.randomBytes(32).toString("base64");
+    const encryptedFilePath = path.join(os.tmpdir(), "dotenc.enc");
+    await encrypt(token, "Test", encryptedFilePath);
+    const content = await decrypt(token, encryptedFilePath);
+    await fs.unlink(encryptedFilePath);
+    if (content !== "Test") {
+        throw new Error("Decrypted content is not equal to the original content");
+    }
+    console.log("Decryption successful");
+};

package/dist/src/commands/edit.js

@@ -0,0 +1,44 @@
+import { execSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { createHash } from "../helpers/createHash";
+import { decrypt, encrypt } from "../helpers/crypto";
+import { getDefaultEditor } from "../helpers/getDefaultEditor";
+import { getToken } from "../helpers/token";
+import { chooseEnvironmentPrompt } from "./prompts/chooseEnvironment";
+export const editCommand = async (environmentArg) => {
+    let environment = environmentArg;
+    if (!environment) {
+        environment = await chooseEnvironmentPrompt("What environment do you want to edit?");
+    }
+    const environmentFilePath = path.join(process.cwd(), `.env.${environment}.enc`);
+    if (!existsSync(environmentFilePath)) {
+        throw new Error(`Environment file not found: ${environmentFilePath}`);
+    }
+    const token = await getToken(environment);
+    const tempFilePath = path.join(os.tmpdir(), `.env.${environment}`);
+    const content = await decrypt(token, environmentFilePath);
+    await fs.writeFile(tempFilePath, content);
+    const initialHash = createHash(content);
+    const editor = await getDefaultEditor();
+    try {
+        // This will block until the editor process is closed
+        execSync(`${editor} ${tempFilePath}`, { stdio: "inherit" });
+    }
+    catch (error) {
+        throw new Error(`Failed to open editor: ${editor}`);
+    }
+    const newContent = await fs.readFile(tempFilePath, "utf-8");
+    const finalHash = createHash(newContent);
+    if (initialHash === finalHash) {
+        console.log(`No changes were made to the environment file for "${environment}".`);
+    }
+    else {
+        await encrypt(token, newContent, environmentFilePath);
+        console.log(`Encrypted environment file for "${environment}" and saved it to ${environmentFilePath}.`);
+    }
+    await fs.unlink(tempFilePath);
+    console.debug(`Temporary file deleted: ${tempFilePath}`);
+};

package/dist/src/commands/init.js

@@ -0,0 +1,29 @@
+import crypto from "node:crypto";
+import { createEnvironment } from "../helpers/createEnvironment";
+import { createLocalEnvironment } from "../helpers/createLocalEnvironment";
+import { createProject } from "../helpers/createProject";
+import { addToken } from "../helpers/token";
+import { createEnvironmentPrompt } from "./prompts/createEnvironment";
+export const initCommand = async (environmentArg) => {
+    // Generate a unique project ID
+    const { projectId } = await createProject();
+    // Setup local environment
+    await createLocalEnvironment();
+    // Generate a random token
+    const token = crypto.randomBytes(32).toString("base64");
+    // Prompt for the environment name
+    let environment = environmentArg;
+    if (!environment) {
+        environment = await createEnvironmentPrompt("What should the environment be named?", "development");
+    }
+    await createEnvironment(environment, token);
+    // Store the token
+    await addToken(projectId, environment, token);
+    // Output success message
+    console.log("Initialization complete!");
+    console.log("Next steps:");
+    console.log(`1. Use "npx dotenc edit -e ${environment}" to securely edit your safe environment variables.`);
+    console.log(`2. Use "npx dotenc run -e ${environment} <command> [args...]" to run your application.`);
+    console.log('3. Use "npx dotenc init -e [environment]" to initialize a new environment.');
+    console.log("4. Use the git-ignored .env file to edit your local environment variables. They will have priority over any safe environment.");
+};

package/dist/src/commands/prompts/chooseEnvironment.js

@@ -0,0 +1,18 @@
+import inquirer from "inquirer";
+import fs from "node:fs/promises";
+export const chooseEnvironmentPrompt = async (message) => {
+    const files = await fs.readdir(process.cwd());
+    const envFiles = files.filter((file) => file.startsWith(".env.") && file.endsWith(".enc"));
+    if (!envFiles.length) {
+        console.log('No environment files found. To create a new environment, run "npx dotenc init"');
+    }
+    const result = await inquirer.prompt([
+        {
+            type: "list",
+            name: "environment",
+            message,
+            choices: envFiles.map((file) => file.replace(".env.", "").replace(".enc", "")),
+        },
+    ]);
+    return result.environment;
+};

package/dist/src/commands/prompts/createEnvironment.js

@@ -0,0 +1,12 @@
+import inquirer from "inquirer";
+export const createEnvironmentPrompt = async (message, defaultValue) => {
+    const result = await inquirer.prompt([
+        {
+            type: "input",
+            name: "environment",
+            message,
+            default: defaultValue,
+        },
+    ]);
+    return result.environment;
+};

package/dist/src/commands/run.js

@@ -0,0 +1,34 @@
+import { spawn } from "node:child_process";
+import { existsSync } from "node:fs";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { decrypt } from "../helpers/crypto";
+import { parseEnv } from "../helpers/parseEnv";
+import { getToken } from "../helpers/token";
+export const runCommand = async (environmentArg, command, args) => {
+    // Get the environment
+    const environment = environmentArg;
+    const environmentFilePath = path.join(process.cwd(), `.env.${environment}.enc`);
+    if (!existsSync(environmentFilePath)) {
+        throw new Error(`Environment file not found: ${environmentFilePath}`);
+    }
+    const token = await getToken(environment);
+    const content = await decrypt(token, environmentFilePath);
+    const decryptedEnv = parseEnv(content);
+    // Get the local environment
+    let localEnv = {};
+    const localEnvironmentFilePath = path.join(process.cwd(), ".env");
+    if (existsSync(localEnvironmentFilePath)) {
+        const localEnvContent = await fs.readFile(localEnvironmentFilePath, "utf-8");
+        localEnv = parseEnv(localEnvContent);
+    }
+    // Merge the environment variables and run the command
+    const mergedEnv = { ...process.env, ...decryptedEnv, ...localEnv };
+    const child = spawn(command, args, {
+        env: mergedEnv,
+        stdio: "inherit",
+    });
+    child.on("exit", (code) => {
+        process.exit(code);
+    });
+};

package/dist/src/commands/token/export.js

@@ -0,0 +1,11 @@
+import { getProjectConfig } from "../../helpers/projectConfig";
+import { getToken } from "../../helpers/token";
+export const tokenExportCommand = async (environmentArg) => {
+    const environment = environmentArg;
+    const { projectId } = await getProjectConfig();
+    if (!projectId) {
+        throw new Error('No project found. Run "npx dotenc init" to create one.');
+    }
+    const token = await getToken(environment);
+    console.log(`Token for the ${environment} environment: ${token}`);
+};

package/dist/src/commands/token/import.js

@@ -0,0 +1,11 @@
+import { getProjectConfig } from "../../helpers/projectConfig";
+import { addToken } from "../../helpers/token";
+export const tokenImportCommand = async (token, environmentArg) => {
+    const environment = environmentArg;
+    const { projectId } = await getProjectConfig();
+    if (!projectId) {
+        throw new Error('No project found. Run "npx dotenc init" to create one.');
+    }
+    await addToken(projectId, environment, token);
+    console.log(`Token imported to the ${environment} environment.`);
+};

package/dist/src/helpers/createEnvironment.js

@@ -0,0 +1,11 @@
+import { existsSync } from "node:fs";
+import path from "node:path";
+import { encrypt } from "./crypto";
+export const createEnvironment = async (name, token) => {
+    const filePath = path.join(process.cwd(), `.env.${name}.enc`);
+    if (existsSync(filePath)) {
+        throw new Error(`Environment "${name}" already exists.`);
+    }
+    await encrypt(token, `# ${name} environment\n`, filePath);
+    console.debug(`Environment "${name}" created.`);
+};

package/dist/src/helpers/createHash.js

@@ -0,0 +1,7 @@
+import crypto from "node:crypto";
+/**
+ * Computes a hash of the input string.
+ */
+export const createHash = (input) => {
+    return crypto.createHash("sha256").update(input).digest("hex");
+};

package/dist/src/helpers/createLocalEnvironment.js

@@ -0,0 +1,29 @@
+import { existsSync } from "node:fs";
+import fs from "node:fs/promises";
+import path from "node:path";
+export const createLocalEnvironment = async () => {
+    const gitignorePath = path.join(process.cwd(), ".gitignore");
+    const envEntry = ".env";
+    let gitignoreContent = [];
+    if (existsSync(gitignorePath)) {
+        gitignoreContent = (await fs.readFile(gitignorePath, "utf8")).split("\n");
+    }
+    // Check if the .env entry already exists (ignoring comments and whitespace)
+    const isEnvIgnored = gitignoreContent.some((line) => line.trim() === envEntry);
+    if (!isEnvIgnored) {
+        // Append the .env entry to the .gitignore file
+        await fs.appendFile(gitignorePath, `\n# Ignore local environment file\n${envEntry}\n`);
+        console.debug("Updated .gitignore to ignore .env file.");
+    }
+    else {
+        console.debug(".env file is already ignored in .gitignore.");
+    }
+    const envPath = path.join(process.cwd(), ".env");
+    if (existsSync(envPath)) {
+        console.debug(".env file already exists.");
+    }
+    else {
+        await fs.writeFile(envPath, "");
+        console.debug("Created .env file.");
+    }
+};

package/dist/src/helpers/createProject.js

@@ -0,0 +1,13 @@
+import { createId } from "@paralleldrive/cuid2";
+import { getProjectConfig, setProjectConfig } from "./projectConfig";
+export const createProject = async () => {
+    const config = await getProjectConfig();
+    if (config.projectId) {
+        return config;
+    }
+    const newConfig = {
+        projectId: createId(),
+    };
+    await setProjectConfig(newConfig);
+    return newConfig;
+};

package/dist/src/helpers/crypto.js

@@ -0,0 +1,72 @@
+import crypto from "node:crypto";
+import fs from "node:fs/promises";
+// AES-256-GCM constants
+const ALGORITHM = "aes-256-gcm";
+const IV_LENGTH = 12; // 96 bits, recommended for GCM
+const AUTH_TAG_LENGTH = 16; // 128 bits, standard for GCM
+/**
+ * Encrypts a file using AES-256-GCM.
+ * @param {string} token - The encryption key (must be 32 bytes for AES-256).
+ * @param {string} input - The input string to encrypt.
+ * @param {string} outputFile - Path to the output encrypted file.
+ */
+export async function encrypt(token, input, outputFile) {
+    const tokenBuffer = Buffer.from(token, "base64");
+    if (tokenBuffer.length !== 32) {
+        throw new Error("Token must be 32 bytes (256 bits) for AES-256-GCM.");
+    }
+    // Generate a random IV
+    const iv = crypto.randomBytes(IV_LENGTH);
+    // Create the cipher
+    const cipher = crypto.createCipheriv(ALGORITHM, tokenBuffer, iv);
+    // Encrypt the data
+    const encrypted = Buffer.concat([cipher.update(input), cipher.final()]);
+    // Get the auth tag
+    const authTag = cipher.getAuthTag();
+    // Combine IV + encrypted content + auth tag
+    const result = Buffer.concat([iv, encrypted, authTag]);
+    // Write the encrypted file
+    await fs.writeFile(outputFile, result);
+    console.debug(`File encrypted successfully: ${outputFile}`);
+}
+/**
+ * Decrypts a file using AES-256-GCM.
+ * @param {string} token - The decryption key (must be 32 bytes for AES-256).
+ * @param {string} inputFile - The input file to decrypt.
+ */
+export async function decrypt(token, inputFile) {
+    const tokenBuffer = Buffer.from(token, "base64");
+    if (tokenBuffer.length !== 32) {
+        throw new Error("Token must be 32 bytes (256 bits) for AES-256-GCM.");
+    }
+    // Read the encrypted file
+    const encryptedData = await fs.readFile(inputFile);
+    // Extract the IV from the start of the file
+    const iv = encryptedData.subarray(0, IV_LENGTH);
+    // Extract the auth tag from the end of the file
+    const authTag = encryptedData.subarray(encryptedData.length - AUTH_TAG_LENGTH);
+    // Extract the ciphertext (everything between IV and auth tag)
+    const ciphertext = encryptedData.subarray(IV_LENGTH, encryptedData.length - AUTH_TAG_LENGTH);
+    try {
+        // Create the decipher
+        const decipher = crypto.createDecipheriv(ALGORITHM, tokenBuffer, iv);
+        decipher.setAuthTag(authTag);
+        // Decrypt the ciphertext
+        const decrypted = Buffer.concat([
+            decipher.update(ciphertext),
+            decipher.final(),
+        ]);
+        console.debug(`File decrypted successfully: ${inputFile}`);
+        return decrypted.toString();
+    }
+    catch (error) {
+        if (error instanceof Error &&
+            error.message.includes("unable to authenticate")) {
+            throw new Error("Failed to decrypt file. This could be because:\n" +
+                "1. The encryption token may be incorrect\n" +
+                "2. The encrypted file may be corrupted\n" +
+                "3. The encrypted file may have been tampered with");
+        }
+        throw error;
+    }
+}

package/dist/src/helpers/getDefaultEditor.js

@@ -0,0 +1,41 @@
+import { execSync } from "node:child_process";
+import { getHomeConfig } from "./homeConfig";
+/**
+ * Determines the default text editor for the system.
+ * @returns {string} The command to launch the default text editor.
+ */
+export const getDefaultEditor = async () => {
+    const config = await getHomeConfig();
+    // Check the editor field in the config file
+    if (config.editor) {
+        return config.editor;
+    }
+    // Check the EDITOR environment variable
+    if (process.env.EDITOR) {
+        return process.env.EDITOR;
+    }
+    // Check the VISUAL environment variable
+    if (process.env.VISUAL) {
+        return process.env.VISUAL;
+    }
+    // Platform-specific defaults
+    const platform = process.platform;
+    if (platform === "win32") {
+        // Windows: Use notepad as the fallback editor
+        return "notepad";
+    }
+    // Linux/macOS: Try nano, vim, or vi
+    const editors = ["nano", "vim", "vi"];
+    for (const editor of editors) {
+        try {
+            // Check if the editor is available
+            execSync(`command -v ${editor}`, { stdio: "ignore" });
+            return editor; // Return the first available editor
+        }
+        catch {
+            // Ignore errors and try the next editor
+        }
+    }
+    // If no editor is found, throw an error
+    throw new Error('No text editor found. Please set the EDITOR environment variable, configure an editor using "npx dotenc config editor <command>", or install a text editor (e.g., nano, vim, or notepad).');
+};

package/dist/src/helpers/homeConfig.js

@@ -0,0 +1,23 @@
+import { existsSync } from "node:fs";
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { z } from "zod";
+const homeConfigSchema = z.object({
+    editor: z.string().nullish(),
+});
+const configPath = path.join(os.homedir(), ".dotenc", "config.json");
+export const setHomeConfig = async (config) => {
+    const parsedConfig = homeConfigSchema.parse(config);
+    await fs.writeFile(configPath, JSON.stringify(parsedConfig, null, 2), {
+        mode: 0o600,
+    });
+    console.debug("config.json saved");
+};
+export const getHomeConfig = async () => {
+    if (existsSync(configPath)) {
+        const config = JSON.parse(await fs.readFile(configPath, "utf-8"));
+        return homeConfigSchema.parse(config);
+    }
+    return {};
+};

package/dist/src/helpers/parseEnv.js

@@ -0,0 +1,21 @@
+/**
+ * Parses a .env file content and returns an object of key-value pairs.
+ */
+export const parseEnv = (content) => {
+    const env = {};
+    const lines = content.split("\n");
+    for (const line of lines) {
+        const trimmedLine = line.trim();
+        // Skip empty lines and comments
+        if (!trimmedLine || trimmedLine.startsWith("#")) {
+            continue;
+        }
+        // Parse key-value pairs
+        const [key, ...valueParts] = trimmedLine.split("=");
+        const value = valueParts.join("=").trim();
+        if (key) {
+            env[key.trim()] = value.replace(/(^['"])|(['"]$)/g, ""); // Remove surrounding quotes
+        }
+    }
+    return env;
+};

package/dist/src/helpers/projectConfig.js

@@ -0,0 +1,22 @@
+import { existsSync } from "node:fs";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { z } from "zod";
+const projectConfigSchema = z.object({
+    projectId: z.string(),
+});
+const configPath = path.join(process.cwd(), "dotenc.json");
+export const setProjectConfig = async (config) => {
+    const parsedConfig = projectConfigSchema.parse(config);
+    await fs.writeFile(configPath, JSON.stringify(parsedConfig, null, 2), {
+        mode: 0o600,
+    });
+    console.debug(`dotenc.json saved for projectId "${parsedConfig.projectId}".`);
+};
+export const getProjectConfig = async () => {
+    if (existsSync(configPath)) {
+        const config = JSON.parse(await fs.readFile(configPath, "utf-8"));
+        return projectConfigSchema.parse(config);
+    }
+    return {};
+};

package/dist/src/helpers/token.js

@@ -0,0 +1,40 @@
+import { existsSync } from "node:fs";
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { getProjectConfig } from "./projectConfig";
+export const getToken = async (environment) => {
+    if (process.env.DOTENC_TOKEN) {
+        return process.env.DOTENC_TOKEN;
+    }
+    const { projectId } = await getProjectConfig();
+    const tokensFile = path.join(os.homedir(), ".dotenc", "tokens.json");
+    if (existsSync(tokensFile)) {
+        const tokens = JSON.parse(await fs.readFile(tokensFile, "utf-8"));
+        return tokens[projectId][environment];
+    }
+    throw new Error("No token found. Please set the TOKEN environment variable or import the token using `npx dotenc import-token -e <environment> <token>`.");
+};
+/**
+ * Adds or updates a token for a specific project and environment.
+ */
+export const addToken = async (projectId, environment, token) => {
+    const tokensFile = path.join(os.homedir(), ".dotenc", "tokens.json");
+    // Ensure the tokens file exists
+    if (!existsSync(tokensFile)) {
+        await fs.mkdir(path.dirname(tokensFile), { recursive: true });
+        await fs.writeFile(tokensFile, "{}", { mode: 0o600 }); // Create an empty JSON file with secure permissions
+    }
+    // Read the existing tokens
+    const tokens = JSON.parse(await fs.readFile(tokensFile, "utf8"));
+    // Add or update the token
+    if (!tokens[projectId]) {
+        tokens[projectId] = {};
+    }
+    tokens[projectId][environment] = token;
+    // Write the updated tokens back to the file
+    await fs.writeFile(tokensFile, JSON.stringify(tokens, null, 2), {
+        mode: 0o600,
+    });
+    console.debug(`Token for project "${projectId}" and environment "${environment}" added successfully.`);
+};

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@dotenc/cli",
+  "version": "0.1.0",
+  "description": "🔐 Secure, encrypted environment variables that live in your codebase",
+  "type": "module",
+  "bin": {
+    "dotenc": "./dist/cli.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "keywords": [
+    "environment",
+    "variables",
+    "safe",
+    "secure",
+    "codebase",
+    "cli",
+    "command",
+    "line",
+    "tool",
+    "utility",
+    "env",
+    "box",
+    "dotenv",
+    "encrypted",
+    "codebase"
+  ],
+  "author": "Ivan Filho <i@ivanfilho.com>",
+  "license": "MIT",
+  "devDependencies": {
+    "@biomejs/biome": "^1.9.4",
+    "@types/node": "^22.13.7",
+    "tsx": "^4.19.3",
+    "typescript": "^5.8.2"
+  },
+  "dependencies": {
+    "@paralleldrive/cuid2": "^2.2.2",
+    "commander": "^13.1.0",
+    "inquirer": "^12.4.2",
+    "zod": "^3.24.2"
+  },
+  "scripts": {
+    "dev": "tsx src/cli.ts",
+    "build": "tsc"
+  }
+}