crabenv 0.0.1

package/README.md

@@ -0,0 +1,112 @@
+# crabenv
+
+The simplest, opinionated way to keep .env files, schemas, and examples aligned.
+
+crabenv is an **opinionated**, language-agnostic CLI that keeps your environment variables aligned across schema, template, and local files. No new config file required. It validates, copies, and checks for drift so your team doesn't have to.
+
+This project will once and for all solve environment variables typesafe schema definition and documentation so it will never drift. This CLI only does what you can already do manually. It doesn't introduce any new config files so if your team doesn't want to use crabenv, it'll be completely fine!
+
+## Installation
+
+```sh
+brew install blankeos/tap/crabenv # Homebrew (macOS/Linux)
+npm install -g crabenv            # or npm
+bun install -g crabenv            # or bun
+cargo binstall crabenv            # or cargo-binstall (prebuilt binary, faster)
+cargo install crabenv             # or cargo (build from source)
+curl -sSL https://raw.githubusercontent.com/Blankeos/crabenv/main/install.sh | sh # or linux/macos (via curl)
+```
+
+### 📁 Languages supported:
+
+- [x] TypeScript/Javascript and Monorepos (includes React, Solid, Vue, Svelte, Vite, NextJS, ReactNative, Backends, and Cloudflare apps)
+- [x] Python
+- [x] Rust
+- [x] Flutter
+- [x] More? Request an adapter.
+
+### 🤒 Pains solved:
+
+- [x] CRUD and Documentation drift
+- [ ] Deployment/sink drift via explicit managed blocks, not arbitrary file inference
+- [x] `.env.example` and `env.ts` drift
+- [x] Validation
+- [x] Client and Server Boundaries
+- [x] Local Development (creating the first .env) to Actual Deployment (translating that into the env on deployment) stories
+- [x] A better `cp .env.example .env` command (This is not enough!) Creating envs (local env or for new dev,staging,prod envs).
+  - [x] Use templating patterns like `"RSA_KEY=$(openssl  rand -base64 32)` - the crabenv copy
+- [x] ~Rotating??~ Kinda impossible actually.
+- [ ] Cloudflare `.dev.vars` guidance/docs
+
+## Philosophy
+
+- No new config file. Your team doesn't have to install crabenv, but it helps a lot! The CLI just abstracts the manual maintenance.
+- Env config is synced across **surfaces**:
+  - 1. **Schema** - The validator language-specific schema. Multiple based on apps. i.e. `env.ts`, `env.private.ts`, `env.public.ts`, `config.rs`, `config.dart`.
+  - 2. **Template (`.env.example`)** - Safe example/template values for env values. Multiple based on apps.
+  - 3. **Local (`.env`)** - The actual local runtime values/secrets. 1 only.
+  - 4. **Sinks** - Reserved for future explicit integrations. crabenv does not currently infer or rewrite arbitrary deployment files.
+  - More? Make an adapter
+- Packages in monorepos don't have .env.
+
+## Agent skill
+
+Install the crabenv skill for coding agents with:
+
+```sh
+npx skills add blankeos/crabenv
+```
+
+This installs the `crabenv` agent skill from `skills/crabenv`, including language-specific references for TypeScript/JavaScript, Python, Rust, and Flutter/Dart.
+
+## Usage
+
+```sh
+crabenv init
+crabenv copy         # or crabenv cp.
+crabenv doctor       # It's a checklist of common mistakes
+crabenv doctor --fix
+
+# CRUD
+crabenv list   # Lists variables
+crabenv add    # Wizard-like experience
+crabenv update # Wizard-like experience
+crabenv remove # Wizard-like experience
+
+crabenv add {VARIABLE_NAME}
+    --shared   # if monorepo, adds it to all apps
+    --example  # optional, for .env.example
+    --optional # optional, required by default
+    --default  # optional
+    # Type flags
+    --string   # optional, passed by default
+    --numeric  # optional, conflicts w/ string. It's a string, but validates as a number (a numeric string)
+    --number   # optional, conflicts w/ string (implicitly z.preprocess(Number))
+    --boolean  # optional, conflicts w/ string (implicitly z.preprocess(Boolean))
+    --enum     # optional, i.e. --enum=development,production
+    # Custom regex
+    --testRegex         # optional
+    --testRegexMessage  # optional, required when used with `testRegex`
+    # ... essentially a cli version of zod
+    # Special environment overrides
+    --{}_development     # Checks env=development, before applying the type
+    --{}_staging         # Checks env=staging, before applying the type
+    --{}_production      # Checks env=production, before applying the type
+    --{}_ci              # Checks CI=true, before applying the type
+crabenv remove {VARIABLE_NAME}
+crabenv update {VARIABLE_NAME} # Same flags as add
+```
+
+## Current CLI
+
+This repo currently has a first Rust CLI implementation that works against the sample projects in `_checks/sample-projects`.
+
+```sh
+crabenv --root _checks/sample-projects/basic-npm list
+crabenv --root _checks/sample-projects/basic-npm doctor
+crabenv --root _checks/sample-projects/basic-npm copy
+
+crabenv --root _checks/sample-projects/monorepo doctor --fix --yes
+crabenv --root _checks/sample-projects/monorepo add NEXT_PUBLIC_ANALYTICS_ID --owner apps/next-web --public --example dev --optional
+crabenv --root _checks/sample-projects/monorepo remove NEXT_PUBLIC_ANALYTICS_ID --owner apps/next-web --public
+```

package/bin.js

@@ -0,0 +1,45 @@
+#!/usr/bin/env node
+
+const { spawn } = require("child_process");
+const path = require("path");
+const fs = require("fs");
+const { install } = require("./install");
+
+const binaryName = process.platform === "win32" ? "crabenv.exe" : "crabenv";
+const binaryPath = path.join(__dirname, "bin", binaryName);
+
+async function ensureBinary() {
+  if (fs.existsSync(binaryPath)) {
+    return;
+  }
+
+  console.error("crabenv binary not found. Attempting download...");
+
+  try {
+    await install();
+  } catch (error) {
+    process.exit(1);
+  }
+
+  if (!fs.existsSync(binaryPath)) {
+    console.error("❌ crabenv binary still missing after download.");
+    process.exit(1);
+  }
+}
+
+async function run() {
+  await ensureBinary();
+
+  const child = spawn(binaryPath, process.argv.slice(2), { stdio: "inherit" });
+
+  child.on("error", (err) => {
+    console.error("❌ Failed to start crabenv:", err.message);
+    process.exit(1);
+  });
+
+  child.on("exit", (code, signal) => {
+    process.exit(signal ? 1 : code || 0);
+  });
+}
+
+run();

package/install.js

@@ -0,0 +1,158 @@
+#!/usr/bin/env node
+
+const { execSync } = require("child_process");
+const fs = require("fs");
+const path = require("path");
+const https = require("https");
+
+// Version should match your Rust crate version.
+const VERSION = require("./package.json").version;
+const BINARY_NAME = "crabenv";
+
+function getPlatformInfo() {
+  const platform = process.platform;
+  const arch = process.arch;
+
+  // Map Node.js platform/arch to Rust target triples.
+  const platformMap = {
+    darwin: {
+      x64: "x86_64-apple-darwin",
+      arm64: "aarch64-apple-darwin",
+    },
+    linux: {
+      x64: "x86_64-unknown-linux-gnu",
+      arm64: "aarch64-unknown-linux-gnu",
+    },
+    win32: {
+      x64: "x86_64-pc-windows-msvc",
+    },
+  };
+
+  if (!platformMap[platform]) {
+    throw new Error(`Unsupported platform: ${platform}`);
+  }
+
+  if (!platformMap[platform][arch]) {
+    throw new Error(`Unsupported architecture: ${arch} on ${platform}`);
+  }
+
+  const target = platformMap[platform][arch];
+  const extension = platform === "win32" ? ".zip" : ".tar.xz";
+  const binaryName = platform === "win32" ? `${BINARY_NAME}.exe` : BINARY_NAME;
+
+  return {
+    target,
+    extension,
+    binaryName,
+    filename: `${BINARY_NAME}-${target}${extension}`,
+    url: `https://github.com/Blankeos/crabenv/releases/download/v${VERSION}/${BINARY_NAME}-${target}${extension}`,
+  };
+}
+
+async function downloadFile(url, dest) {
+  console.log(`Downloading ${url}...`);
+
+  const file = fs.createWriteStream(dest);
+  const response = await new Promise((resolve, reject) => {
+    https
+      .get(url, (res) => {
+        if (res.statusCode === 302 || res.statusCode === 301) {
+          https.get(res.headers.location, resolve).on("error", reject);
+        } else if (res.statusCode === 200) {
+          resolve(res);
+        } else {
+          reject(new Error(`Failed to download: ${res.statusCode} ${res.statusMessage}`));
+        }
+      })
+      .on("error", reject);
+  });
+
+  response.pipe(file);
+  return new Promise((resolve, reject) => {
+    file.on("finish", () => {
+      file.close();
+      resolve();
+    });
+    file.on("error", (err) => {
+      fs.unlink(dest, () => {});
+      reject(err);
+    });
+  });
+}
+
+function extractArchive(archivePath, extractDir, platformInfo) {
+  console.log("Extracting binary...");
+
+  const cmd =
+    platformInfo.extension === ".zip"
+      ? `unzip -o "${archivePath}" -d "${extractDir}" 2>/dev/null || powershell -command "Expand-Archive -Path '${archivePath}' -DestinationPath '${extractDir}' -Force"`
+      : `tar -xf "${archivePath}" -C "${extractDir}"`;
+
+  execSync(cmd, { stdio: "inherit" });
+}
+
+function logInstallFailure(error) {
+  const message = error instanceof Error ? error.message : String(error);
+  console.error("Installation failed:", message);
+  console.error("\nYou can install crabenv directly using:");
+  console.error(
+    'curl --proto "=https" --tlsv1.2 -LsSf https://github.com/Blankeos/crabenv/releases/latest/download/crabenv-installer.sh | sh',
+  );
+}
+
+async function install({ exitOnComplete = false } = {}) {
+  try {
+    const platformInfo = getPlatformInfo();
+    const binDir = path.join(__dirname, "bin");
+    const archivePath = path.join(__dirname, platformInfo.filename);
+    const binaryPath = path.join(binDir, platformInfo.binaryName);
+
+    if (!fs.existsSync(binDir)) fs.mkdirSync(binDir, { recursive: true });
+
+    await downloadFile(platformInfo.url, archivePath);
+    extractArchive(archivePath, __dirname, platformInfo);
+
+    const extractedBinaryPath = path.join(__dirname, platformInfo.binaryName);
+    if (fs.existsSync(extractedBinaryPath)) {
+      fs.renameSync(extractedBinaryPath, binaryPath);
+    } else {
+      const subdirPath = path.join(__dirname, `${BINARY_NAME}-${platformInfo.target}`, platformInfo.binaryName);
+      if (fs.existsSync(subdirPath)) {
+        fs.renameSync(subdirPath, binaryPath);
+        fs.rmSync(path.dirname(subdirPath), { recursive: true, force: true });
+      } else {
+        throw new Error("Binary not found after extraction");
+      }
+    }
+
+    if (process.platform !== "win32") {
+      fs.chmodSync(binaryPath, 0o755);
+    }
+
+    fs.unlinkSync(archivePath);
+    console.log(`crabenv v${VERSION} installed successfully!`);
+
+    if (exitOnComplete) {
+      process.exit(0);
+      return binaryPath;
+    }
+
+    return binaryPath;
+  } catch (error) {
+    logInstallFailure(error);
+
+    if (exitOnComplete) {
+      process.exit(1);
+      return;
+    }
+
+    throw error;
+  }
+}
+
+// Only run install if this script is executed directly.
+if (require.main === module) {
+  install({ exitOnComplete: true });
+}
+
+module.exports = { getPlatformInfo, install };

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "crabenv",
+  "version": "0.0.1",
+  "description": "The simplest, opinionated way to keep .env files, schemas, and examples aligned.",
+  "main": "bin.js",
+  "bin": {
+    "crabenv": "./bin.js"
+  },
+  "scripts": {
+    "postinstall": "node install.js"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/blankeos/crabenv.git"
+  },
+  "keywords": [
+    "env",
+    "cli",
+    "config",
+    "dotenv",
+    "schema"
+  ],
+  "author": "Blankeos",
+  "license": "MIT",
+  "files": [
+    "install.js",
+    "bin.js",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=12"
+  },
+  "os": [
+    "darwin",
+    "linux",
+    "win32"
+  ]
+}