xtrm-cli 2.1.4

package/src/utils/env-manager.ts

@@ -0,0 +1,193 @@
+import fs from 'fs-extra';
+import path from 'path';
+import os from 'os';
+import kleur from 'kleur';
+import dotenv from 'dotenv';
+
+/**
+ * Environment file location: ~/.config/jaggers-agent-tools/.env
+ */
+const CONFIG_DIR = path.join(os.homedir(), '.config', 'jaggers-agent-tools');
+const ENV_FILE = path.join(CONFIG_DIR, '.env');
+const ENV_EXAMPLE_FILE = path.join(CONFIG_DIR, '.env.example');
+
+interface EnvVarConfig {
+    description: string;
+    example: string;
+    getUrl: () => string;
+}
+
+/**
+ * Required environment variables for MCP servers
+ */
+const REQUIRED_ENV_VARS: Record<string, EnvVarConfig> = {
+    CONTEXT7_API_KEY: {
+        description: 'Context7 MCP server API key',
+        example: 'ctx7sk-your-api-key-here',
+        getUrl: () => 'https://context7.com/',
+    },
+};
+
+/**
+ * Ensure config directory and .env file exist
+ */
+export function ensureEnvFile(): boolean {
+    // Create config directory if missing
+    if (!fs.existsSync(CONFIG_DIR)) {
+        fs.ensureDirSync(CONFIG_DIR);
+        console.log(kleur.gray(`  Created config directory: ${CONFIG_DIR}`));
+    }
+
+    // Create .env.example if missing
+    if (!fs.existsSync(ENV_EXAMPLE_FILE)) {
+        createEnvExample();
+    }
+
+    // Create .env if missing
+    if (!fs.existsSync(ENV_FILE)) {
+        createEnvFile();
+        return false; // File was created (user needs to fill it)
+    }
+
+    return true; // File already exists
+}
+
+function createEnvExample(): void {
+    const content = [
+        '# Jaggers Agent Tools - Environment Variables',
+        '# Copy this file to .env and fill in your actual values',
+        '',
+        ...Object.entries(REQUIRED_ENV_VARS).map(([key, config]) => {
+            return [
+                `# ${config.description}`,
+                `# Get your key from: ${config.getUrl()}`,
+                `${key}=${config.example}`,
+                '',
+            ].join('\n');
+        }),
+        '# See config/.env.example in the repository for all available options',
+        '',
+    ].join('\n');
+
+    fs.writeFileSync(ENV_EXAMPLE_FILE, content);
+    console.log(kleur.gray(`  Created example file: ${ENV_EXAMPLE_FILE}`));
+}
+
+function createEnvFile(): void {
+    const content = [
+        '# Jaggers Agent Tools - Environment Variables',
+        '# Generated automatically by jaggers-agent-tools CLI',
+        '',
+        '# Copy values from .env.example and fill in your actual keys',
+        '',
+    ].join('\n');
+
+    fs.writeFileSync(ENV_FILE, content);
+    console.log(kleur.green(`  Created environment file: ${ENV_FILE}`));
+}
+
+/**
+ * Load environment variables from .env file
+ * Also loads from process.env (which takes precedence)
+ */
+export function loadEnvFile(): Record<string, string> {
+    if (fs.existsSync(ENV_FILE)) {
+        const envConfig = dotenv.parse(fs.readFileSync(ENV_FILE));
+
+        // Merge with process.env (process.env takes precedence)
+        for (const [key, value] of Object.entries(envConfig)) {
+            if (!process.env[key]) {
+                process.env[key] = value;
+            }
+        }
+
+        return envConfig;
+    }
+
+    return {};
+}
+
+/**
+ * Check if required environment variables are set.
+ * Pass an optional `subset` of var names to check only those.
+ * Known vars (in REQUIRED_ENV_VARS) get rich metadata; unknown vars are
+ * still checked so server-defined ${VAR} references are never silently dropped.
+ * Returns array of missing variable names.
+ */
+export function checkRequiredEnvVars(subset?: string[]): string[] {
+    const missing: string[] = [];
+    const keysToCheck = subset ?? Object.keys(REQUIRED_ENV_VARS);
+
+    for (const key of keysToCheck) {
+        if (!process.env[key]) {
+            missing.push(key);
+        }
+    }
+
+    return missing;
+}
+
+/**
+ * Prompt user to enter missing environment variables interactively.
+ * Saves provided values to .env and sets them in process.env.
+ * Returns true if all missing vars were provided (sync can continue).
+ */
+export async function handleMissingEnvVars(missing: string[]): Promise<boolean> {
+    if (missing.length === 0) {
+        return true;
+    }
+
+    // @ts-ignore
+    const prompts = (await import('prompts')).default;
+
+    const answers: Record<string, string> = {};
+
+    for (const key of missing) {
+        const config = REQUIRED_ENV_VARS[key];
+        if (config) {
+            console.log(kleur.yellow(`\n  ⚠️  ${config.description} is required`));
+            console.log(kleur.dim(`     Get your key from: ${config.getUrl()}`));
+        } else {
+            console.log(kleur.yellow(`\n  ⚠️  ${key} is required by a selected MCP server`));
+        }
+
+        const { value } = await prompts({
+            type: 'text',
+            name: 'value',
+            message: `Enter ${key}:`,
+            validate: (v: string) => v.trim().length > 0 || 'Value cannot be empty'
+        });
+
+        if (!value) {
+            console.log(kleur.gray(`  Skipped — ${key} not provided. MCP server will be skipped.`));
+            return false;
+        }
+
+        answers[key] = value.trim();
+        process.env[key] = value.trim();
+    }
+
+    // Persist to .env file
+    let envContent = fs.existsSync(ENV_FILE) ? fs.readFileSync(ENV_FILE, 'utf8') : '';
+    for (const [key, value] of Object.entries(answers)) {
+        const line = `${key}=${value}`;
+        const regex = new RegExp(`^${key}=.*$`, 'm');
+        if (regex.test(envContent)) {
+            envContent = envContent.replace(regex, line);
+        } else {
+            envContent += `\n${line}\n`;
+        }
+    }
+    fs.writeFileSync(ENV_FILE, envContent);
+    console.log(kleur.green(`  ✓ Saved to ${ENV_FILE}`));
+
+    return true;
+}
+
+export function getEnvFilePath(): string {
+    return ENV_FILE;
+}
+
+export function getConfigDir(): string {
+    return CONFIG_DIR;
+}

package/src/utils/hash.ts

@@ -0,0 +1,42 @@
+import { createHash } from 'crypto';
+import fs from 'fs-extra';
+import { join } from 'path';
+
+export async function hashFile(filePath: string): Promise<string> {
+    const content = await fs.readFile(filePath);
+    return createHash('md5').update(content).digest('hex');
+}
+
+export async function hashDirectory(dirPath: string): Promise<string> {
+    if (!(await fs.pathExists(dirPath))) return '';
+    const stats = await fs.stat(dirPath);
+
+    if (!stats.isDirectory()) {
+        return hashFile(dirPath);
+    }
+
+    const children = await fs.readdir(dirPath);
+    const childHashes = await Promise.all(
+        children.sort().map(async (child) => {
+            const h = await hashDirectory(join(dirPath, child));
+            return `${child}:${h}`;
+        })
+    );
+    return createHash('md5').update(childHashes.join('|')).digest('hex');
+}
+
+export async function getNewestMtime(targetPath: string): Promise<number> {
+    if (!(await fs.pathExists(targetPath))) return 0;
+
+    const stats = await fs.stat(targetPath);
+    let maxTime = 0;
+
+    if (stats.isDirectory()) {
+        const children = await fs.readdir(targetPath);
+        for (const child of children) {
+            const childTime = await getNewestMtime(join(targetPath, child));
+            if (childTime > maxTime) maxTime = childTime;
+        }
+    }
+    return maxTime;
+}

package/src/utils/repo-root.ts

@@ -0,0 +1,39 @@
+import fs from 'fs-extra';
+import path from 'path';
+
+async function walkUp(startDir: string): Promise<string | null> {
+    let dir = path.resolve(startDir);
+
+    while (true) {
+        const skillsPath = path.join(dir, 'skills');
+        const hooksPath  = path.join(dir, 'hooks');
+
+        if (await fs.pathExists(skillsPath) && await fs.pathExists(hooksPath)) {
+            return dir;
+        }
+
+        const parent = path.dirname(dir);
+        if (parent === dir) return null;
+        dir = parent;
+    }
+}
+
+/**
+ * Finds the jaggers-agent-tools repo root by:
+ * 1. Walking up from process.cwd() — works when run inside a cloned repo.
+ * 2. Walking up from __dirname    — works when run via `npx`, where the
+ *    package is extracted to a temp/cache directory that contains skills/ & hooks/.
+ */
+export async function findRepoRoot(): Promise<string> {
+    const fromCwd = await walkUp(process.cwd());
+    if (fromCwd) return fromCwd;
+
+    // __dirname is cli/dist/ inside the package — two levels up is the repo root.
+    const fromBundle = await walkUp(path.resolve(__dirname, '..', '..'));
+    if (fromBundle) return fromBundle;
+
+    throw new Error(
+        'Could not locate jaggers-agent-tools repo root.\n' +
+        'Run via `npx -y github:Jaggerxtrm/jaggers-agent-tools` or from within the cloned repository.'
+    );
+}