swarmdo 1.11.0 → 1.12.0

package/.claude/helpers/statusline.cjs

@@ -515,7 +515,7 @@ function getCostFromStdin() {
 // misses, the displayed version is meaningful (matches what the user
 // installed), not a stale hard-coded string.
 function getPkgVersion() {
-  let ver = '1.11.0';
+  let ver = '1.12.0';
   try {
     const home = os.homedir();
     const pkgPaths = [

package/README.md

@@ -2,7 +2,7 @@
 
 [![swarmdo](swarmdo/assets/brand/logo-full.svg)](https://swarmdo.com)
 
-[![npm version (swarmdo)](https://img.shields.io/badge/npx%20swarmdo-v1.11.0-cb3837?style=for-the-badge&logo=npm&logoColor=white)](https://github.com/SwarmDo/swarmdo/releases)
+[![npm version (swarmdo)](https://img.shields.io/badge/npx%20swarmdo-v1.12.0-cb3837?style=for-the-badge&logo=npm&logoColor=white)](https://github.com/SwarmDo/swarmdo/releases)
 [![MIT License](https://img.shields.io/badge/License-MIT-yellow?style=for-the-badge)](https://github.com/SwarmDo/swarmdo/blob/main/LICENSE)
 [![Website](https://img.shields.io/badge/swarmdo.com-e2a33c?style=for-the-badge&logoColor=black)](https://swarmdo.com)
 [![Star on GitHub](https://img.shields.io/github/stars/SwarmDo/swarmdo?style=for-the-badge&logo=github&color=gold)](https://github.com/SwarmDo/swarmdo)
@@ -280,6 +280,7 @@ The recent release train added a full day-to-day operations layer around the swa
 | `swarmdo codegraph` (alias `cg`) | **Queryable symbol index** — `codegraph index` scans TS/JS for exported symbols; `query <name>` (with `--fuzzy`/`--kind`) and `file <path>` answer "where is X defined / what does this file export" from `.swarm/codegraph.json` instead of grep+read round-trips. `codegraph importers <file>` shows reverse deps ("what breaks if I change this"); `codegraph imports <file>` shows a file's dependencies. 1,786 symbols + import graph across 296 files in <1s. Also MCP tools (`codegraph_query`/`file`/`imports`/`importers`/`index`/`stats`) so agents query the graph in-session |
 | `swarmdo redact` | **Mask secrets before they reach an LLM/log/memory** — detect API keys, tokens, and private keys (gitleaks-style rule catalog + Shannon-entropy fallback) and redact them. Stdin filter (`cat deploy.log \| swarmdo redact`), command-wrap (`swarmdo redact -- npm run deploy`), or `--scan` to fail CI on any secret. Also MCP tools (`redact_text`/`redact_scan`). Deterministic, zero tokens |
 | `swarmdo pack` | **Bundle a repo into one AI-context blob** — walk the tree (respects `.gitignore` + glob `--include`/`--exclude`, skips binaries/node_modules), emit markdown/xml/json/plain with a directory tree and per-file + total token estimates. `swarmdo pack --tokens` for a budget breakdown; `--redact` masks secrets first. Deterministic |
+| `swarmdo env` | **Catch env-var drift before deploy** — statically scan code for `process.env.X` / `import.meta.env.X` / `Deno.env.get` / `os.getenv` references and reconcile against `.env` and `.env.example`: reports **missing** (used but undeclared), **unused**, and **undocumented**. `--ci` exits 1 on missing vars. Also an MCP tool (`env_check`). Deterministic |
 | `swarmdo integrations` (alias `integrate`) | **Use swarmdo from Codex CLI, GitHub Copilot CLI, and pi** — one command wires AGENTS.md + each CLI's MCP config (idempotent, dry-run first, never touches your Claude Code setup) |
 | OpenRouter model pool | **Let swarms pick from any models you configure** — declare tier-mapped OpenRouter models in `swarmdo.config.json`; the router Thompson-samples among them per task and the execution layer dispatches the winner |
 | `swarmdo changelog` (alias `notes`) | **Release notes from conventional commits** — `--out NOTES.md` feeds `gh release create --notes-file` |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "swarmdo",
-  "version": "1.11.0",
+  "version": "1.12.0",
   "description": "Swarmdo - Enterprise AI agent orchestration for Claude Code. Deploy 60+ specialized agents in coordinated swarms with self-learning, fault-tolerant consensus, vector memory, and MCP integration",
   "main": "dist/index.js",
   "type": "module",

package/v3/@swarmdo/cli/dist/src/commands/env.d.ts

@@ -0,0 +1,16 @@
+/**
+ * `swarmdo env` — reconcile the env vars the code references against what
+ * `.env` declares (and, if present, `.env.example`). Catches deploy-breaking
+ * drift before it ships:
+ *
+ *   swarmdo env                     # scan cwd vs .env / .env.example
+ *   swarmdo env src --ci            # exit 1 if any referenced var is undeclared
+ *   swarmdo env --json              # machine-readable report
+ *
+ * Engine (../env/env.ts) is pure + tested; this layer does the fs walk and
+ * reads the dotenv files.
+ */
+import type { Command } from '../types.js';
+export declare const envCommand: Command;
+export default envCommand;
+//# sourceMappingURL=env.d.ts.map

package/v3/@swarmdo/cli/dist/src/commands/env.js

@@ -0,0 +1,137 @@
+/**
+ * `swarmdo env` — reconcile the env vars the code references against what
+ * `.env` declares (and, if present, `.env.example`). Catches deploy-breaking
+ * drift before it ships:
+ *
+ *   swarmdo env                     # scan cwd vs .env / .env.example
+ *   swarmdo env src --ci            # exit 1 if any referenced var is undeclared
+ *   swarmdo env --json              # machine-readable report
+ *
+ * Engine (../env/env.ts) is pure + tested; this layer does the fs walk and
+ * reads the dotenv files.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { output } from '../output.js';
+import { extractEnvRefs, parseDotenv, reconcile, formatEnvSummary } from '../env/env.js';
+const SOURCE_EXT = new Set(['.ts', '.tsx', '.js', '.jsx', '.mts', '.cts', '.mjs', '.cjs', '.py', '.vue', '.svelte', '.astro']);
+const SKIP_DIRS = new Set([
+    'node_modules', '.git', '.swarm', 'dist', 'dist-standalone', 'build',
+    'coverage', '.next', '.turbo', 'out', 'vendor', '.cache',
+]);
+// Ubiquitous runtime/CI vars that are almost never declared in a project .env.
+const DEFAULT_IGNORE = ['NODE_ENV', 'CI', 'PATH', 'HOME', 'PWD', 'USER', 'SHELL', 'TERM', 'TZ', 'LANG'];
+function walk(root) {
+    const found = [];
+    const stack = [root];
+    while (stack.length) {
+        const dir = stack.pop();
+        let entries;
+        try {
+            entries = fs.readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        for (const e of entries) {
+            const full = path.join(dir, e.name);
+            if (e.isDirectory()) {
+                if (SKIP_DIRS.has(e.name))
+                    continue;
+                stack.push(full);
+            }
+            else if (e.isFile()) {
+                const ext = path.extname(e.name);
+                if (SOURCE_EXT.has(ext) && !e.name.endsWith('.d.ts'))
+                    found.push(full);
+            }
+        }
+    }
+    return found;
+}
+function readKeys(file) {
+    try {
+        return parseDotenv(fs.readFileSync(file, 'utf8'));
+    }
+    catch {
+        return null;
+    }
+}
+async function run(ctx) {
+    const repoRoot = ctx.cwd || process.cwd();
+    const scanRoot = ctx.args[0] ? path.resolve(repoRoot, ctx.args[0]) : repoRoot;
+    const envFile = path.resolve(repoRoot, typeof ctx.flags.env === 'string' ? ctx.flags.env : '.env');
+    const exampleFlag = typeof ctx.flags.example === 'string' ? ctx.flags.example : '.env.example';
+    const exampleFile = path.resolve(repoRoot, exampleFlag);
+    const declared = readKeys(envFile);
+    if (declared === null) {
+        output.printError(`no env file at ${path.relative(repoRoot, envFile)} (use --env <file>)`);
+        return { success: false, exitCode: 1 };
+    }
+    const example = readKeys(exampleFile) ?? undefined;
+    const ignore = [...DEFAULT_IGNORE];
+    if (typeof ctx.flags.ignore === 'string')
+        ignore.push(...ctx.flags.ignore.split(',').map((s) => s.trim()).filter(Boolean));
+    const refs = [];
+    for (const abs of walk(scanRoot)) {
+        let src;
+        try {
+            src = fs.readFileSync(abs, 'utf8');
+        }
+        catch {
+            continue;
+        }
+        const rel = path.relative(repoRoot, abs).split(path.sep).join('/');
+        refs.push(...extractEnvRefs(src, rel));
+    }
+    const report = reconcile({ refs, declared, example, ignore });
+    const hasExample = example !== undefined;
+    if (ctx.flags.json === true) {
+        output.printJson({ ...report, envFile: path.relative(repoRoot, envFile), hasExample });
+    }
+    else {
+        const section = (title, keys, withSites = false) => {
+            if (keys.length === 0)
+                return;
+            output.writeln(output.bold(`${title} (${keys.length})`));
+            output.printList(keys.map((k) => {
+                if (!withSites)
+                    return k;
+                const site = report.refs[k]?.[0];
+                return site ? `${k}  ${output.dim(`${site.file}:${site.line}`)}` : k;
+            }));
+        };
+        section('Missing — referenced in code, not in .env', report.missing, true);
+        section('Unused — declared in .env, never referenced', report.unused);
+        if (hasExample)
+            section('Undocumented — in .env, not in .env.example', report.undocumented);
+        output.writeln(output.dim(formatEnvSummary(report, hasExample)));
+    }
+    // --ci gates on `missing` (the runtime-breaking bucket); --strict also gates
+    // on unused + undocumented.
+    const strict = ctx.flags.strict === true;
+    const bad = report.missing.length + (strict ? report.unused.length + report.undocumented.length : 0);
+    const gate = ctx.flags.ci === true || strict;
+    const code = gate && bad > 0 ? 1 : 0;
+    return { success: code === 0, exitCode: code };
+}
+export const envCommand = {
+    name: 'env',
+    description: 'Reconcile env vars referenced in code against .env / .env.example — find missing, unused, and undocumented vars',
+    options: [
+        { name: 'env', description: 'path to the env file (default .env)', type: 'string' },
+        { name: 'example', description: 'path to the example env file (default .env.example)', type: 'string' },
+        { name: 'ignore', description: 'comma-separated extra keys to ignore (NODE_ENV/CI/… already ignored)', type: 'string' },
+        { name: 'ci', description: 'exit 1 if any referenced var is undeclared (missing bucket)', type: 'boolean' },
+        { name: 'strict', description: 'exit 1 on missing OR unused OR undocumented', type: 'boolean' },
+        { name: 'json', description: 'machine-readable report', type: 'boolean' },
+    ],
+    examples: [
+        { command: 'swarmdo env', description: 'Reconcile the repo against .env / .env.example' },
+        { command: 'swarmdo env src --ci', description: 'Fail CI if code references an undeclared var' },
+        { command: 'swarmdo env --env .env.production --json', description: 'Check a specific env file, JSON out' },
+    ],
+    action: run,
+};
+export default envCommand;
+//# sourceMappingURL=env.js.map

package/v3/@swarmdo/cli/dist/src/commands/index.js

@@ -28,6 +28,9 @@ const commandLoaders = {
     // Repo→AI-context bundle (repomix demand) — one promptable blob with tree +
     // token counts; swarmdo's context-assembly primitive.
     pack: () => import('./pack.js'),
+    // Env-var drift checker (dotenv-safe/dotenv-scan demand) — reconcile code
+    // references against .env / .env.example (missing/unused/undocumented).
+    env: () => import('./env.js'),
     // Queryable exported-symbol index (codegraph demand) — where things are
     // defined without grep+read round-trips.
     codegraph: () => import('./codegraph.js'),
@@ -261,7 +264,7 @@ export async function getCommandsByCategory() {
     // three slots from 'statusline' onward (completionsCmd received the
     // statusline module, analyzeCmd received completions, …), scrambling the
     // categorized help. Every load now has a named slot.
-    const [daemonCmd, doctorCmd, embeddingsCmd, neuralCmd, performanceCmd, securityCmd, swarmvectorCmd, hiveMindCmd, configCmd, statuslineCmd, compressCmd, efficiencyCmd, completionsCmd, migrateCmd, workflowCmd, analyzeCmd, routeCmd, progressCmd, providersCmd, pluginsCmd, deploymentCmd, claimsCmd, issuesCmd, updateCmd, processCmd, guidanceCmd, applianceCmd, cleanupCmd, autopilotCmd, demoCmd, usageCmd, repairCmd, hudCmd, compactCmd, codegraphCmd, redactCmd, packCmd,] = await Promise.all([
+    const [daemonCmd, doctorCmd, embeddingsCmd, neuralCmd, performanceCmd, securityCmd, swarmvectorCmd, hiveMindCmd, configCmd, statuslineCmd, compressCmd, efficiencyCmd, completionsCmd, migrateCmd, workflowCmd, analyzeCmd, routeCmd, progressCmd, providersCmd, pluginsCmd, deploymentCmd, claimsCmd, issuesCmd, updateCmd, processCmd, guidanceCmd, applianceCmd, cleanupCmd, autopilotCmd, demoCmd, usageCmd, repairCmd, hudCmd, compactCmd, codegraphCmd, redactCmd, packCmd, envCmd,] = await Promise.all([
         loadCommand('daemon'), loadCommand('doctor'), loadCommand('embeddings'), loadCommand('neural'),
         loadCommand('performance'), loadCommand('security'), loadCommand('swarmvector'), loadCommand('hive-mind'),
         loadCommand('config'), loadCommand('statusline'), loadCommand('compress'), loadCommand('efficiency'),
@@ -269,7 +272,7 @@ export async function getCommandsByCategory() {
         loadCommand('analyze'), loadCommand('route'), loadCommand('progress'), loadCommand('providers'),
         loadCommand('plugins'), loadCommand('deployment'), loadCommand('claims'), loadCommand('issues'),
         loadCommand('update'), loadCommand('process'), loadCommand('guidance'), loadCommand('appliance'),
-        loadCommand('cleanup'), loadCommand('autopilot'), loadCommand('demo'), loadCommand('usage'), loadCommand('repair'), loadCommand('hud'), loadCommand('compact'), loadCommand('codegraph'), loadCommand('redact'), loadCommand('pack'),
+        loadCommand('cleanup'), loadCommand('autopilot'), loadCommand('demo'), loadCommand('usage'), loadCommand('repair'), loadCommand('hud'), loadCommand('compact'), loadCommand('codegraph'), loadCommand('redact'), loadCommand('pack'), loadCommand('env'),
     ]);
     return {
         primary: [
@@ -285,7 +288,7 @@ export async function getCommandsByCategory() {
         utility: [
             configCmd, doctorCmd, daemonCmd, completionsCmd,
             migrateCmd, workflowCmd, demoCmd,
-            statuslineCmd, compressCmd, compactCmd, redactCmd, packCmd, efficiencyCmd,
+            statuslineCmd, compressCmd, compactCmd, redactCmd, packCmd, envCmd, efficiencyCmd,
         ].filter(Boolean),
         analysis: [
             analyzeCmd, routeCmd, progressCmd, usageCmd, hudCmd, codegraphCmd,

package/v3/@swarmdo/cli/dist/src/env/env.d.ts

@@ -0,0 +1,49 @@
+/**
+ * env.ts — reconcile the environment variables a codebase *references* against
+ * the ones a `.env` (and `.env.example`) *declares*. Catches the classic "deploy
+ * broke because a var was missing / stale" drift before it ships.
+ *
+ * Three buckets:
+ *   missing      — referenced in code, not declared in .env        (will break at runtime)
+ *   unused       — declared in .env, never referenced in code      (dead config)
+ *   undocumented — declared in .env, absent from .env.example      (onboarding gap)
+ *
+ * Pure + deterministic (regex extraction + dotenv parse + set diff), so it's
+ * fully fixture-testable with zero LLM calls. The fs walk + file reads live in
+ * ../commands/env.ts; this module just takes strings.
+ */
+export interface EnvRef {
+    key: string;
+    file: string;
+    /** 1-based line */
+    line: number;
+}
+export interface EnvReport {
+    missing: string[];
+    unused: string[];
+    undocumented: string[];
+    /** every key referenced in code → the sites that reference it */
+    refs: Record<string, EnvRef[]>;
+}
+/** Extract env-var references from one source file. Pure. */
+export declare function extractEnvRefs(source: string, file: string): EnvRef[];
+/**
+ * Parse a `.env` file into an ordered list of declared keys. Handles `KEY=val`,
+ * `export KEY=val`, quoted values, `# comments`, and blank lines. Values are
+ * ignored — we only reconcile key presence. Pure.
+ */
+export declare function parseDotenv(text: string): string[];
+export interface ReconcileInput {
+    refs: EnvRef[];
+    /** keys declared in .env */
+    declared: string[];
+    /** keys declared in .env.example (optional) */
+    example?: string[];
+    /** keys to ignore in all buckets (e.g. NODE_ENV, CI) */
+    ignore?: string[];
+}
+/** Compute the missing / unused / undocumented buckets. Pure. */
+export declare function reconcile(input: ReconcileInput): EnvReport;
+/** One-line human summary. */
+export declare function formatEnvSummary(r: EnvReport, hasExample: boolean): string;
+//# sourceMappingURL=env.d.ts.map

package/v3/@swarmdo/cli/dist/src/env/env.js

@@ -0,0 +1,103 @@
+/**
+ * env.ts — reconcile the environment variables a codebase *references* against
+ * the ones a `.env` (and `.env.example`) *declares*. Catches the classic "deploy
+ * broke because a var was missing / stale" drift before it ships.
+ *
+ * Three buckets:
+ *   missing      — referenced in code, not declared in .env        (will break at runtime)
+ *   unused       — declared in .env, never referenced in code      (dead config)
+ *   undocumented — declared in .env, absent from .env.example      (onboarding gap)
+ *
+ * Pure + deterministic (regex extraction + dotenv parse + set diff), so it's
+ * fully fixture-testable with zero LLM calls. The fs walk + file reads live in
+ * ../commands/env.ts; this module just takes strings.
+ */
+/**
+ * Patterns that read an env var. Each capture group 1 is the var name. Covers
+ * Node (`process.env.X`, `process.env['X']`), Vite (`import.meta.env.X`), Deno
+ * (`Deno.env.get('X')`), and Python (`os.environ['X']`, `os.environ.get('X')`,
+ * `os.getenv('X')`). Deterministic, line-based.
+ */
+const REF_PATTERNS = [
+    /process\.env\.([A-Za-z_][A-Za-z0-9_]*)/g,
+    /process\.env\[\s*['"`]([^'"`]+)['"`]\s*\]/g,
+    /import\.meta\.env\.([A-Za-z_][A-Za-z0-9_]*)/g,
+    /import\.meta\.env\[\s*['"`]([^'"`]+)['"`]\s*\]/g,
+    /Deno\.env\.get\(\s*['"`]([^'"`]+)['"`]\s*\)/g,
+    /os\.environ\[\s*['"]([^'"]+)['"]\s*\]/g,
+    /os\.environ\.get\(\s*['"]([^'"]+)['"]\s*\)/g,
+    /os\.getenv\(\s*['"]([^'"]+)['"]\s*\)/g,
+];
+/** Non-secret prefixes on `import.meta.env` that are Vite builtins, not user vars. */
+const VITE_BUILTINS = new Set(['MODE', 'BASE_URL', 'PROD', 'DEV', 'SSR']);
+/** Extract env-var references from one source file. Pure. */
+export function extractEnvRefs(source, file) {
+    const out = [];
+    const lines = source.split('\n');
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        if (!line.includes('env') && !line.includes('getenv'))
+            continue;
+        for (const re of REF_PATTERNS) {
+            re.lastIndex = 0;
+            let m;
+            while ((m = re.exec(line)) !== null) {
+                const key = m[1];
+                if (VITE_BUILTINS.has(key))
+                    continue;
+                out.push({ key, file, line: i + 1 });
+            }
+        }
+    }
+    return out;
+}
+/**
+ * Parse a `.env` file into an ordered list of declared keys. Handles `KEY=val`,
+ * `export KEY=val`, quoted values, `# comments`, and blank lines. Values are
+ * ignored — we only reconcile key presence. Pure.
+ */
+export function parseDotenv(text) {
+    const keys = [];
+    const seen = new Set();
+    for (const raw of text.split('\n')) {
+        const line = raw.trim();
+        if (!line || line.startsWith('#'))
+            continue;
+        const m = line.match(/^(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=/);
+        if (!m)
+            continue;
+        if (seen.has(m[1]))
+            continue;
+        seen.add(m[1]);
+        keys.push(m[1]);
+    }
+    return keys;
+}
+/** Compute the missing / unused / undocumented buckets. Pure. */
+export function reconcile(input) {
+    const ignore = new Set(input.ignore ?? []);
+    const refByKey = {};
+    for (const r of input.refs) {
+        if (ignore.has(r.key))
+            continue;
+        (refByKey[r.key] ??= []).push(r);
+    }
+    const referenced = new Set(Object.keys(refByKey));
+    const declared = new Set(input.declared.filter((k) => !ignore.has(k)));
+    const missing = [...referenced].filter((k) => !declared.has(k)).sort();
+    const unused = [...declared].filter((k) => !referenced.has(k)).sort();
+    let undocumented = [];
+    if (input.example) {
+        const example = new Set(input.example);
+        undocumented = [...declared].filter((k) => !example.has(k)).sort();
+    }
+    return { missing, unused, undocumented, refs: refByKey };
+}
+/** One-line human summary. */
+export function formatEnvSummary(r, hasExample) {
+    const parts = [`${r.missing.length} missing`, `${r.unused.length} unused`];
+    if (hasExample)
+        parts.push(`${r.undocumented.length} undocumented`);
+    return `env: ${parts.join(', ')}`;
+}
+//# sourceMappingURL=env.js.map

package/v3/@swarmdo/cli/dist/src/mcp-client.js

@@ -21,6 +21,7 @@ import { workflowTools } from './mcp-tools/workflow-tools.js';
 import { analyzeTools } from './mcp-tools/analyze-tools.js';
 import { codegraphTools } from './mcp-tools/codegraph-tools.js';
 import { redactTools } from './mcp-tools/redact-tools.js';
+import { envTools } from './mcp-tools/env-tools.js';
 import { progressTools } from './mcp-tools/progress-tools.js';
 import { embeddingsTools } from './mcp-tools/embeddings-tools.js';
 import { claimsTools } from './mcp-tools/claims-tools.js';
@@ -106,6 +107,7 @@ const TOOL_GROUPS = {
     analyze: () => analyzeTools,
     codegraph: () => codegraphTools,
     redact: () => redactTools,
+    env: () => envTools,
     progress: () => progressTools,
     embeddings: () => embeddingsTools,
     claims: () => claimsTools,

package/v3/@swarmdo/cli/dist/src/mcp-tools/env-tools.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Env MCP Tool
+ *
+ * Let an agent check env-var drift in-session before it writes code that reads
+ * a var, or before it green-lights a deploy: reconcile the vars referenced in
+ * given source against a `.env` (and optional `.env.example`). Deterministic —
+ * shares the pure engine in ../env/env.ts with the CLI command. String-in, so
+ * it works without touching the filesystem.
+ */
+import type { MCPTool } from './types.js';
+export declare const envTools: MCPTool[];
+//# sourceMappingURL=env-tools.d.ts.map

package/v3/@swarmdo/cli/dist/src/mcp-tools/env-tools.js

@@ -0,0 +1,62 @@
+/**
+ * Env MCP Tool
+ *
+ * Let an agent check env-var drift in-session before it writes code that reads
+ * a var, or before it green-lights a deploy: reconcile the vars referenced in
+ * given source against a `.env` (and optional `.env.example`). Deterministic —
+ * shares the pure engine in ../env/env.ts with the CLI command. String-in, so
+ * it works without touching the filesystem.
+ */
+import { extractEnvRefs, parseDotenv, reconcile } from '../env/env.js';
+const envCheckTool = {
+    name: 'env_check',
+    description: 'Reconcile env vars referenced in source code against a .env declaration. Returns missing (referenced, not declared — will break at runtime), unused (declared, never referenced), and undocumented (in .env, not in .env.example). Use before adding a var or approving a deploy. Deterministic; pass the file contents directly.',
+    category: 'env',
+    tags: ['env', 'dotenv', 'config', 'drift', 'ci'],
+    inputSchema: {
+        type: 'object',
+        properties: {
+            sources: {
+                type: 'array',
+                description: 'source files to scan',
+                items: {
+                    type: 'object',
+                    properties: {
+                        path: { type: 'string', description: 'file path (for reporting)' },
+                        content: { type: 'string', description: 'file contents' },
+                    },
+                    required: ['path', 'content'],
+                },
+            },
+            env: { type: 'string', description: 'contents of the .env file (declarations)' },
+            example: { type: 'string', description: 'contents of .env.example (optional, enables the undocumented bucket)' },
+            ignore: { type: 'array', items: { type: 'string' }, description: 'extra keys to ignore' },
+        },
+        required: ['sources', 'env'],
+    },
+    handler: async (params) => {
+        const sources = params.sources;
+        if (!Array.isArray(sources))
+            return { error: true, message: 'sources[] is required' };
+        if (typeof params.env !== 'string')
+            return { error: true, message: 'env (string) is required' };
+        const refs = sources.flatMap((s) => {
+            const o = s;
+            if (typeof o.path !== 'string' || typeof o.content !== 'string')
+                return [];
+            return extractEnvRefs(o.content, o.path);
+        });
+        const declared = parseDotenv(params.env);
+        const example = typeof params.example === 'string' ? parseDotenv(params.example) : undefined;
+        const ignore = Array.isArray(params.ignore) ? params.ignore.filter((x) => typeof x === 'string') : undefined;
+        const report = reconcile({ refs, declared, example, ignore });
+        return {
+            clean: report.missing.length === 0 && report.unused.length === 0 && report.undocumented.length === 0,
+            missing: report.missing,
+            unused: report.unused,
+            undocumented: report.undocumented,
+        };
+    },
+};
+export const envTools = [envCheckTool];
+//# sourceMappingURL=env-tools.js.map

package/v3/@swarmdo/cli/dist/src/mcp-tools/index.d.ts

@@ -17,6 +17,7 @@ export { coverageRouterTools } from '../swarmvector/coverage-tools.js';
 export { analyzeTools } from './analyze-tools.js';
 export { codegraphTools } from './codegraph-tools.js';
 export { redactTools } from './redact-tools.js';
+export { envTools } from './env-tools.js';
 export { progressTools } from './progress-tools.js';
 export { transferTools } from './transfer-tools.js';
 export { securityTools } from './security-tools.js';

package/v3/@swarmdo/cli/dist/src/mcp-tools/index.js

@@ -16,6 +16,7 @@ export { coverageRouterTools } from '../swarmvector/coverage-tools.js';
 export { analyzeTools } from './analyze-tools.js';
 export { codegraphTools } from './codegraph-tools.js';
 export { redactTools } from './redact-tools.js';
+export { envTools } from './env-tools.js';
 export { progressTools } from './progress-tools.js';
 export { transferTools } from './transfer-tools.js';
 export { securityTools } from './security-tools.js';

package/v3/@swarmdo/cli/dist/src/mcp-tools/profiles.js

@@ -24,6 +24,7 @@ const LEAN_GROUPS = [
     'embeddings', // embeddings_generate / search / compare
     'codegraph', // codegraph_query / file / index — "where is X defined?"
     'redact', // redact_text / redact_scan — secret guard on the data path
+    'env', // env_check — env-var drift (missing/unused/undocumented)
 ];
 /** Balanced = lean + orchestration/session/system the average user reaches for. */
 const BALANCED_EXTRA = [

package/v3/@swarmdo/cli/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@swarmdo/cli",
-  "version": "1.11.0",
+  "version": "1.12.0",
   "type": "module",
   "description": "Swarmdo CLI - Enterprise AI agent orchestration with 60+ specialized agents, swarm coordination, MCP server, self-learning hooks, and vector memory for Claude Code",
   "main": "dist/src/index.js",