dotscribe 0.1.0

package/LICENSE

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

package/README.md

@@ -0,0 +1,15 @@
+# cli
+
+To install dependencies:
+
+```bash
+bun install
+```
+
+To run:
+
+```bash
+bun run index.ts
+```
+
+This project was created using `bun init` in bun v1.3.13. [Bun](https://bun.com) is a fast all-in-one JavaScript runtime.

package/index.ts

@@ -0,0 +1,339 @@
+#!/usr/bin/env bun
+import { readFileSync, existsSync } from "fs";
+import { resolve } from "path";
+import { createInterface } from "readline";
+
+const MISTRAL_API_KEY = process.env.MISTRAL_API_KEY;
+const API_BASE = process.env.DOTSCRIBE_API_URL || "http://localhost:3000";
+
+interface AnalyzedVariable {
+  key: string;
+  description: string;
+  type: string;
+  required: boolean;
+  source?: string;
+  example?: string;
+}
+
+interface CliOptions {
+  output?: string;
+  markdown: boolean;
+  strict: boolean;
+  envPath?: string;
+  stdin: boolean;
+  help: boolean;
+}
+
+const COLORS = {
+  reset: "\x1b[0m",
+  bright: "\x1b[1m",
+  dim: "\x1b[2m",
+  green: "\x1b[32m",
+  yellow: "\x1b[33m",
+  red: "\x1b[31m",
+  cyan: "\x1b[36m",
+  gray: "\x1b[90m",
+};
+
+function log(msg: string, color = "") {
+  console.log(color + msg + COLORS.reset);
+}
+
+function error(msg: string) {
+  log(`Error: ${msg}`, COLORS.red);
+}
+
+function warn(msg: string) {
+  log(`Warning: ${msg}`, COLORS.yellow);
+}
+
+function info(msg: string) {
+  log(msg, COLORS.cyan);
+}
+
+function success(msg: string) {
+  log(msg, COLORS.green);
+}
+
+function dim(msg: string) {
+  log(msg, COLORS.gray);
+}
+
+function parseArgs(): CliOptions {
+  const args = process.argv.slice(2);
+  const options: CliOptions = {
+    markdown: false,
+    strict: false,
+    stdin: false,
+    help: false,
+  };
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === undefined) continue;
+    if (arg === "-o" || arg === "--output") {
+      options.output = args[++i];
+    } else if (arg === "--markdown" || arg === "-m") {
+      options.markdown = true;
+    } else if (arg === "--strict" || arg === "-s") {
+      options.strict = true;
+    } else if (arg === "--stdin") {
+      options.stdin = true;
+    } else if (arg === "--help" || arg === "-h") {
+      options.help = true;
+    } else if (!arg.startsWith("-")) {
+      options.envPath = arg;
+    }
+  }
+
+  return options;
+}
+
+function findEnvFile(path?: string): string | null {
+  const searchPaths = path
+    ? [resolve(path)]
+    : [
+        resolve(".env"),
+        resolve(process.cwd(), ".env"),
+        resolve(process.cwd(), ".env.local"),
+      ];
+
+  for (const p of searchPaths) {
+    if (existsSync(p)) {
+      return p;
+    }
+  }
+  return null;
+}
+
+function parseEnvContent(content: string): string[] {
+  const lines = content.split(/\r?\n/);
+  const keys: string[] = [];
+
+  for (const line of lines) {
+    let trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith("#")) continue;
+
+    const commentIndex = trimmed.indexOf("#");
+    if (commentIndex > 0) {
+      trimmed = trimmed.slice(0, commentIndex).trim();
+    }
+    if (!trimmed) continue;
+
+    const equalsIndex = trimmed.indexOf("=");
+    if (equalsIndex === -1) continue;
+
+    const key = trimmed.slice(0, equalsIndex).trim();
+    if (key) keys.push(key);
+  }
+
+  return keys;
+}
+
+function detectPotentialSecrets(keys: string[]): string[] {
+  const secretPatterns = [
+    /secret/i,
+    /password/i,
+    /key/i,
+    /token/i,
+    /api_key/i,
+    /apikey/i,
+    /private/i,
+    /credential/i,
+  ];
+
+  return keys.filter((key) => secretPatterns.some((p) => p.test(key)));
+}
+
+async function callApi(endpoint: string, body: unknown): Promise<unknown> {
+  const response = await fetch(`${API_BASE}${endpoint}`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify(body),
+  });
+
+  if (!response.ok) {
+    const err = await response.json().catch(() => ({ error: "Unknown error" }));
+    throw new Error((err as { error: string }).error || `API error: ${response.status}`);
+  }
+
+  return response.json();
+}
+
+async function analyzeEnv(content: string): Promise<AnalyzedVariable[]> {
+  const result = (await callApi("/api/analyze", { content })) as { variables: AnalyzedVariable[] };
+  return result.variables;
+}
+
+async function formatEnv(variables: AnalyzedVariable[], asMarkdown: boolean) {
+  const result = (await callApi("/api/format", {
+    variables,
+    options: { includeDescriptions: true },
+  })) as { envExample: string; markdownTable: string };
+
+  return asMarkdown ? result.markdownTable : result.envExample;
+}
+
+async function checkHealth(): Promise<boolean> {
+  try {
+    const response = await fetch(`${API_BASE}/api/health`);
+    return response.ok;
+  } catch {
+    return false;
+  }
+}
+
+async function readStdin(): Promise<string> {
+  return new Promise((resolve) => {
+    let content = "";
+    process.stdin.on("data", (chunk) => (content += chunk.toString()));
+    process.stdin.on("end", () => resolve(content));
+  });
+}
+
+function printHelp() {
+  log(`
+${COLORS.bright}dotscribe${COLORS.reset} - Document your .env files with AI
+
+${COLORS.bright}USAGE:${COLORS.reset}
+  dotscribe [OPTIONS] [ENV_FILE]
+
+${COLORS.bright}OPTIONS:${COLORS.reset}
+  -o, --output <file>    Save output to file
+  -m, --markdown         Output as markdown table
+  -s, --strict           Fail if secrets detected without .gitignore
+      --stdin            Read .env from stdin
+  -h, --help             Show this help message
+
+${COLORS.bright}EXAMPLES:${COLORS.reset}
+  dotscribe                         Analyze .env in current directory
+  dotscribe .env.production          Analyze specific file
+  dotscribe -o .env.example         Save to file
+  dotscribe --markdown              Output as markdown table
+  dotscribe --strict                Fail on secrets without protection
+  cat .env | dotscribe --stdin      Read from pipe
+
+${COLORS.bright}ENVIRONMENT:${COLORS.reset}
+  MISTRAL_API_KEY       Your Mistral API key (for local development)
+  DOTSCRIBE_API_URL     API endpoint (default: http://localhost:3000)
+`);
+}
+
+async function main() {
+  const options = parseArgs();
+
+  if (options.help) {
+    printHelp();
+    process.exit(0);
+  }
+
+  dim("dotscribe v0.1.0");
+  console.log();
+
+  info("Checking API health...");
+  const healthy = await checkHealth();
+  
+  if (!healthy) {
+    warn("API not reachable at " + API_BASE);
+    warn("Make sure the API server is running: bun run dev --filter=web");
+    console.log();
+    
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    const answer = await new Promise<string>((resolve) => {
+      rl.question("Continue anyway? (y/N): ", resolve);
+    });
+    rl.close();
+    
+    if (answer.toLowerCase() !== "y") {
+      process.exit(1);
+    }
+  } else {
+    success("API is healthy");
+  }
+  console.log();
+
+  let content: string;
+
+  if (options.stdin) {
+    info("Reading from stdin...");
+    content = await readStdin();
+  } else {
+    const envPath = findEnvFile(options.envPath);
+    if (!envPath) {
+      error("No .env file found. Specify a path or run in a directory with .env");
+      process.exit(1);
+    }
+    info(`Reading from ${envPath}...`);
+    content = readFileSync(envPath, "utf-8");
+  }
+
+  const keys = parseEnvContent(content);
+  if (keys.length === 0) {
+    error("No valid environment variables found");
+    process.exit(1);
+  }
+
+  success(`Found ${keys.length} environment variable(s)`);
+  console.log();
+
+  if (options.strict) {
+    const secrets = detectPotentialSecrets(keys);
+    if (secrets.length > 0) {
+      const hasGitignore = existsSync(resolve(".gitignore"));
+      if (!hasGitignore) {
+        warn(`Potential secrets detected: ${secrets.join(", ")}`);
+        warn("No .gitignore found - these values will be committed!");
+        
+        const rl = createInterface({ input: process.stdin, output: process.stdout });
+        const answer = await new Promise<string>((resolve) => {
+          rl.question("Continue anyway? (y/N): ", resolve);
+        });
+        rl.close();
+        
+        if (answer.toLowerCase() !== "y") {
+          process.exit(1);
+        }
+      }
+    }
+  }
+
+  info("Analyzing environment variables...");
+
+  let variables: AnalyzedVariable[];
+  try {
+    variables = await analyzeEnv(content);
+  } catch (e) {
+    error(`Analysis failed: ${(e as Error).message}`);
+    process.exit(1);
+  }
+
+  success(`Analyzed ${variables.length} variable(s)`);
+  console.log();
+
+  info("Generating documentation...");
+  let output: string;
+  try {
+    output = await formatEnv(variables, options.markdown);
+  } catch (e) {
+    error(`Formatting failed: ${(e as Error).message}`);
+    process.exit(1);
+  }
+
+  if (options.output) {
+    const outputPath = resolve(options.output);
+    import("fs").then(({ writeFileSync }) => {
+      writeFileSync(outputPath, output, "utf-8");
+      success(`Saved to ${outputPath}`);
+    });
+  } else {
+    console.log(output);
+  }
+
+  console.log();
+  success("Done!");
+}
+
+main().catch((e) => {
+  error((e as Error).message);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "dotscribe",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Document your .env files with AI — interactive CLI that analyzes env vars and generates docs",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/your-org/dotscribe.git"
+  },
+  "bugs": {
+    "url": "https://github.com/your-org/dotscribe/issues"
+  },
+  "homepage": "https://github.com/your-org/dotscribe#readme",
+  "keywords": [
+    "dotenv",
+    "env",
+    "environment-variables",
+    "documentation",
+    "cli",
+    "ai"
+  ],
+  "bin": {
+    "dotscribe": "./index.ts"
+  },
+  "scripts": {
+    "dev": "bun run index.ts",
+    "start": "bun run index.ts",
+    "build": "echo \"CLI has no build output\"",
+    "lint": "echo \"CLI has no lint\"",
+    "check-types": "tsc --noEmit",
+    "prepublishOnly": "bunx tsc --noEmit"
+  },
+  "files": ["index.ts", "README.md", "LICENSE"],
+  "devDependencies": {
+    "@types/bun": "latest",
+    "typescript": "^5"
+  }
+}