swarmdo 1.10.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.10.0';
+  let ver = '1.12.0';
   try {
     const home = os.homedir();
     const pkgPaths = [

package/README.md

@@ -1,8 +1,8 @@
 <div align="center">
 
-[![swarmdo](swarmdo/assets/swarmdo-banner.svg)](https://swarmdo.com)
+[![swarmdo](swarmdo/assets/brand/logo-full.svg)](https://swarmdo.com)
 
-[![npm version (swarmdo)](https://img.shields.io/badge/npx%20swarmdo-v1.10.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)
@@ -277,9 +277,10 @@ The recent release train added a full day-to-day operations layer around the swa
 | `swarmdo worktree` (alias `wt`) | **Parallel-agent isolation** on git worktrees — add / list / diff / merge / remove |
 | `swarmdo transcript` (alias `tx`) | **Export any Claude Code session** to clean markdown — system noise stripped, ready to share; `transcript search <query>` full-text-searches every session |
 | `swarmdo compact` | **Compress noisy command output** before it reaches an LLM — strip ANSI, collapse repeats, fold `node_modules` stack frames, window long logs. `npm test 2>&1 \| swarmdo compact` or `swarmdo compact -- npm test` (exit code propagates). Deterministic, zero tokens |
-| `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. 1,750 symbols across 289 files in <1s. Also exposed as MCP tools (`codegraph_query`/`file`/`index`/`stats`) so agents query the index in-session |
+| `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.10.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/codegraph/codegraph.d.ts

@@ -21,13 +21,39 @@ export interface CodeSymbol {
     /** The trimmed declaration line (signature), truncated for storage. */
     signature: string;
 }
+/** A dependency edge: `from` imports module `spec`, resolved to a repo file when relative. */
+export interface ImportEdge {
+    /** repo-relative file containing the import */
+    from: string;
+    /** the raw module specifier as written, e.g. './store.js' or 'node:fs' */
+    spec: string;
+    /** repo-relative file the spec resolves to, or null for external/unresolved */
+    resolved: string | null;
+    /** 1-based line of the import */
+    line: number;
+}
 export interface CodeIndex {
     /** Repo-relative file → symbols declared in it. */
     symbols: CodeSymbol[];
+    /** Dependency edges between files (relative imports resolved; externals kept unresolved). */
+    imports: ImportEdge[];
     fileCount: number;
 }
 /** Extract exported symbols from one source file. Pure. */
 export declare function extractSymbols(source: string, file: string): CodeSymbol[];
+/** Extract the raw import specifiers from one source file. Pure. */
+export declare function extractImports(source: string, file: string): Array<{
+    from: string;
+    spec: string;
+    line: number;
+}>;
+/**
+ * Resolve a spec to a repo-relative file in `fileSet`, or null. Only relative
+ * specs (`.`/`..`) resolve; bare specifiers (packages, aliases, `node:`) are
+ * external → null. Tries the path as-is, common extensions, and `/index.*`,
+ * and rewrites a `.js` spec to its `.ts` sibling (TS ESM convention).
+ */
+export declare function resolveImport(fromFile: string, spec: string, fileSet: Set<string>): string | null;
 /** Build an index from already-read files. Pure. */
 export declare function buildIndex(files: Array<{
     file: string;
@@ -43,10 +69,18 @@ export interface QueryOptions {
 export declare function queryIndex(index: CodeIndex, name: string, opts?: QueryOptions): CodeSymbol[];
 /** Symbols declared in a specific file (exact repo-relative path). Pure. */
 export declare function symbolsInFile(index: CodeIndex, file: string): CodeSymbol[];
+/** Edges FROM a file — what it imports (resolved repo files + external specs). Pure. */
+export declare function fileImports(index: CodeIndex, file: string): ImportEdge[];
+/** Edges TO a file — who imports it ("what breaks if I change this"). Pure. */
+export declare function fileImporters(index: CodeIndex, file: string): ImportEdge[];
 export interface IndexStats {
     files: number;
     symbols: number;
     byKind: Record<string, number>;
+    /** total import edges */
+    imports: number;
+    /** edges resolved to an in-repo file (vs external packages) */
+    internalImports: number;
 }
 /** Summary counts for the index. Pure. */
 export declare function indexStats(index: CodeIndex): IndexStats;

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

@@ -57,15 +57,96 @@ export function extractSymbols(source, file) {
     }
     return out;
 }
+/**
+ * Module specifiers on a line, from any of: `import … from 'x'`,
+ * `export … from 'x'`, side-effect `import 'x'`, `require('x')`, and dynamic
+ * `import('x')`. Line-based like the symbol matchers; captures every spec on
+ * the line (dynamic imports can be mid-line).
+ */
+const IMPORT_RES = [
+    /\bfrom\s*['"]([^'"]+)['"]/g, // import/export … from '…'
+    /\bimport\s*['"]([^'"]+)['"]/g, // side-effect import '…'
+    /\bimport\s*\(\s*['"]([^'"]+)['"]\s*\)/g, // dynamic import('…')
+    /\brequire\s*\(\s*['"]([^'"]+)['"]\s*\)/g, // require('…')
+];
+/** Extract the raw import specifiers from one source file. Pure. */
+export function extractImports(source, file) {
+    const out = [];
+    const lines = source.split('\n');
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        if (!/\b(?:from|import|require)\b/.test(line))
+            continue;
+        const seen = new Set();
+        for (const re of IMPORT_RES) {
+            re.lastIndex = 0;
+            let m;
+            while ((m = re.exec(line)) !== null) {
+                const spec = m[1];
+                if (seen.has(spec))
+                    continue; // same spec caught by two patterns on one line
+                seen.add(spec);
+                out.push({ from: file, spec, line: i + 1 });
+            }
+        }
+    }
+    return out;
+}
+/** Normalize a relative spec against the importing file's dir → repo-relative POSIX path (no extension). */
+function joinRelative(fromFile, spec) {
+    const parts = fromFile.includes('/') ? fromFile.slice(0, fromFile.lastIndexOf('/')).split('/') : [];
+    for (const seg of spec.split('/')) {
+        if (seg === '' || seg === '.')
+            continue;
+        if (seg === '..')
+            parts.pop();
+        else
+            parts.push(seg);
+    }
+    return parts.join('/');
+}
+const RESOLVE_EXTS = ['', '.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs', '.mts', '.cts'];
+/**
+ * Resolve a spec to a repo-relative file in `fileSet`, or null. Only relative
+ * specs (`.`/`..`) resolve; bare specifiers (packages, aliases, `node:`) are
+ * external → null. Tries the path as-is, common extensions, and `/index.*`,
+ * and rewrites a `.js` spec to its `.ts` sibling (TS ESM convention).
+ */
+export function resolveImport(fromFile, spec, fileSet) {
+    if (!spec.startsWith('.'))
+        return null;
+    const base = joinRelative(fromFile, spec);
+    const bases = [base];
+    const jsExt = base.match(/\.(js|jsx|mjs|cjs)$/);
+    if (jsExt)
+        bases.push(base.slice(0, -jsExt[0].length)); // ./x.js → try ./x(.ts…)
+    for (const b of bases) {
+        for (const ext of RESOLVE_EXTS) {
+            if (fileSet.has(b + ext))
+                return b + ext;
+        }
+        for (const ext of RESOLVE_EXTS.slice(1)) {
+            if (fileSet.has(b + '/index' + ext))
+                return b + '/index' + ext;
+        }
+    }
+    return null;
+}
 /** Build an index from already-read files. Pure. */
 export function buildIndex(files) {
     const symbols = [];
+    const fileSet = new Set(files.map((f) => f.file));
+    const imports = [];
     for (const { file, source } of files) {
         symbols.push(...extractSymbols(source, file));
+        for (const imp of extractImports(source, file)) {
+            imports.push({ ...imp, resolved: resolveImport(imp.from, imp.spec, fileSet) });
+        }
     }
     // Stable order: file, then line.
     symbols.sort((a, b) => (a.file < b.file ? -1 : a.file > b.file ? 1 : a.line - b.line));
-    return { symbols, fileCount: files.length };
+    imports.sort((a, b) => (a.from < b.from ? -1 : a.from > b.from ? 1 : a.line - b.line));
+    return { symbols, imports, fileCount: files.length };
 }
 /** Look up symbols by name. Pure. */
 export function queryIndex(index, name, opts = {}) {
@@ -80,11 +161,26 @@ export function queryIndex(index, name, opts = {}) {
 export function symbolsInFile(index, file) {
     return index.symbols.filter((s) => s.file === file);
 }
+/** Edges FROM a file — what it imports (resolved repo files + external specs). Pure. */
+export function fileImports(index, file) {
+    return (index.imports ?? []).filter((e) => e.from === file);
+}
+/** Edges TO a file — who imports it ("what breaks if I change this"). Pure. */
+export function fileImporters(index, file) {
+    return (index.imports ?? []).filter((e) => e.resolved === file);
+}
 /** Summary counts for the index. Pure. */
 export function indexStats(index) {
     const byKind = {};
     for (const s of index.symbols)
         byKind[s.kind] = (byKind[s.kind] ?? 0) + 1;
-    return { files: index.fileCount, symbols: index.symbols.length, byKind };
+    const imports = index.imports ?? [];
+    return {
+        files: index.fileCount,
+        symbols: index.symbols.length,
+        byKind,
+        imports: imports.length,
+        internalImports: imports.filter((e) => e.resolved !== null).length,
+    };
 }
 //# sourceMappingURL=codegraph.js.map

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

@@ -13,11 +13,15 @@
  */
 import * as path from 'node:path';
 import { output } from '../output.js';
-import { queryIndex, symbolsInFile, indexStats, } from '../codegraph/codegraph.js';
+import { queryIndex, symbolsInFile, indexStats, fileImports, fileImporters, } from '../codegraph/codegraph.js';
 import { INDEX_REL, scanRepo, saveIndex, loadIndex } from '../codegraph/store.js';
 function fmtSymbol(s) {
     return `${s.file}:${s.line}  ${output.dim(`[${s.kind}]`)} ${s.signature}`;
 }
+/** Accept an absolute or cwd-relative path; return the repo-relative key. */
+function relKey(root, arg) {
+    return path.relative(root, path.resolve(root, arg)).split(path.sep).join('/');
+}
 const indexCommand = {
     name: 'index',
     description: 'Scan the tree for exported symbols and persist the index',
@@ -124,32 +128,102 @@ const statsCommand = {
             output.printJson(stats);
             return { success: true, data: stats };
         }
-        output.writeln(output.bold(`codegraph: ${stats.symbols} symbols, ${stats.files} files`));
+        output.writeln(output.bold(`codegraph: ${stats.symbols} symbols, ${stats.files} files, ${stats.imports} imports (${stats.internalImports} internal)`));
         output.printList(Object.entries(stats.byKind).sort((a, b) => b[1] - a[1]).map(([k, n]) => `${k}: ${n}`));
         return { success: true, exitCode: 0 };
     },
 };
+const importsCommand = {
+    name: 'imports',
+    description: 'What a file imports — resolved repo files + external packages',
+    options: [
+        { name: 'internal', description: 'only edges resolved to a repo file (hide external packages)', type: 'boolean', default: false },
+        { name: 'json', description: 'machine-readable output', type: 'boolean', default: false },
+    ],
+    action: async (ctx) => {
+        const root = ctx.cwd || process.cwd();
+        const arg = ctx.args[0];
+        if (!arg) {
+            output.printError('Usage: swarmdo codegraph imports <path>');
+            return { success: false, exitCode: 1 };
+        }
+        const index = loadIndex(root);
+        if (!index) {
+            output.printError(`no index — run \`swarmdo codegraph index\` first`);
+            return { success: false, exitCode: 1 };
+        }
+        let edges = fileImports(index, relKey(root, arg));
+        if (ctx.flags.internal === true)
+            edges = edges.filter((e) => e.resolved !== null);
+        if (ctx.flags.json === true) {
+            output.printJson(edges);
+            return { success: true, data: edges };
+        }
+        if (edges.length === 0) {
+            output.writeln(output.dim(`no imports in ${relKey(root, arg)} (indexed?)`));
+            return { success: true, exitCode: 0 };
+        }
+        for (const e of edges) {
+            output.writeln(`  ${e.line}  ${e.spec}${e.resolved ? output.dim(` → ${e.resolved}`) : output.dim(' (external)')}`);
+        }
+        return { success: true, exitCode: 0 };
+    },
+};
+const importersCommand = {
+    name: 'importers',
+    aliases: ['rdeps'],
+    description: 'Who imports a file — reverse deps ("what breaks if I change this")',
+    options: [{ name: 'json', description: 'machine-readable output', type: 'boolean', default: false }],
+    action: async (ctx) => {
+        const root = ctx.cwd || process.cwd();
+        const arg = ctx.args[0];
+        if (!arg) {
+            output.printError('Usage: swarmdo codegraph importers <path>');
+            return { success: false, exitCode: 1 };
+        }
+        const index = loadIndex(root);
+        if (!index) {
+            output.printError(`no index — run \`swarmdo codegraph index\` first`);
+            return { success: false, exitCode: 1 };
+        }
+        const edges = fileImporters(index, relKey(root, arg));
+        if (ctx.flags.json === true) {
+            output.printJson(edges);
+            return { success: true, data: edges };
+        }
+        if (edges.length === 0) {
+            output.writeln(output.dim(`nothing imports ${relKey(root, arg)} (leaf, entrypoint, or not indexed)`));
+            return { success: true, exitCode: 0 };
+        }
+        for (const e of edges)
+            output.writeln(`  ${e.from}:${e.line}  ${output.dim(e.spec)}`);
+        return { success: true, exitCode: 0 };
+    },
+};
 export const codegraphCommand = {
     name: 'codegraph',
     aliases: ['cg'],
-    description: 'Queryable index of exported symbols — where things are defined, without grep+read',
-    subcommands: [indexCommand, queryCommand, fileCommand, statsCommand],
+    description: 'Queryable index of exported symbols + import graph — where things are defined and what depends on what, without grep+read',
+    subcommands: [indexCommand, queryCommand, fileCommand, importsCommand, importersCommand, statsCommand],
     options: [],
     examples: [
-        { command: 'swarmdo codegraph index', description: 'Scan the repo and persist the symbol index' },
+        { command: 'swarmdo codegraph index', description: 'Scan the repo and persist the symbol + import index' },
         { command: 'swarmdo codegraph query buildIndex', description: 'Find where a symbol is defined' },
         { command: 'swarmdo codegraph query Handler --fuzzy --kind type', description: 'Fuzzy, kind-filtered lookup' },
         { command: 'swarmdo codegraph file src/index.ts', description: 'What a file exports' },
+        { command: 'swarmdo codegraph importers src/codegraph/store.ts', description: 'What breaks if I change this file' },
     ],
     action: async () => {
-        output.writeln(output.bold('swarmdo codegraph — exported-symbol index'));
+        output.writeln(output.bold('swarmdo codegraph — exported-symbol index + import graph'));
         output.printList([
-            'index [path]   scan TS/JS and persist to .swarm/codegraph.json',
-            'query <name>   find a symbol (--fuzzy, --kind)',
-            'file <path>    symbols a file exports',
-            'stats          index summary',
+            'index [path]      scan TS/JS and persist to .swarm/codegraph.json',
+            'query <name>      find a symbol (--fuzzy, --kind)',
+            'file <path>       symbols a file exports',
+            'imports <path>    what a file imports (--internal)',
+            'importers <path>  who imports a file (reverse deps)',
+            'stats             index summary',
         ]);
-        output.writeln(output.dim('MVP: exported top-level symbols. Call-graph edges + watch + MCP tool are follow-ups.'));
+        output.writeln(output.dim('MVP: exported top-level symbols + relative-import edges. Incremental watch is a follow-up.'));
         return { success: true, exitCode: 0 };
     },
 };

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/codegraph-tools.js

@@ -6,7 +6,7 @@
  * instead of shelling out to `swarmdo codegraph` or grep+read. Reads the same
  * .swarm/codegraph.json the CLI writes (shared fs layer in codegraph/store.ts).
  */
-import { queryIndex, symbolsInFile, indexStats } from '../codegraph/codegraph.js';
+import { queryIndex, symbolsInFile, indexStats, fileImports, fileImporters } from '../codegraph/codegraph.js';
 import { INDEX_REL, scanRepo, saveIndex, loadIndex } from '../codegraph/store.js';
 const KINDS = ['function', 'class', 'interface', 'type', 'const', 'enum', 'default'];
 /** Resolve the repo root for scan/load. Params may override; default = cwd. */
@@ -113,10 +113,65 @@ const codegraphStatsTool = {
         return indexStats(index);
     },
 };
+const codegraphImportsTool = {
+    name: 'codegraph_imports',
+    description: 'List what a file imports — each edge as the raw specifier plus the repo file it resolves to (external packages resolve to null). Answers "what does this module depend on" from the index. Requires a prior codegraph_index.',
+    category: 'codegraph',
+    tags: ['code', 'imports', 'dependencies', 'navigation'],
+    inputSchema: {
+        type: 'object',
+        properties: {
+            file: { type: 'string', description: 'Repo-relative file path (as indexed, e.g. src/index.ts)' },
+            internal: { type: 'boolean', description: 'only edges resolved to a repo file (hide external packages)', default: false },
+            root: { type: 'string', description: 'Repo root (default: current working directory)' },
+        },
+        required: ['file'],
+    },
+    handler: async (params) => {
+        const root = rootOf(params);
+        const file = params.file;
+        if (typeof file !== 'string' || !file)
+            return { error: true, message: 'file is required' };
+        const index = loadIndex(root);
+        if (!index)
+            return { error: true, message: 'no index — run codegraph_index first' };
+        let edges = fileImports(index, file);
+        if (params.internal === true)
+            edges = edges.filter((e) => e.resolved !== null);
+        return { file, count: edges.length, edges };
+    },
+};
+const codegraphImportersTool = {
+    name: 'codegraph_importers',
+    description: 'List which files import a given file — its reverse dependencies. Use before changing or moving a file to see what depends on it ("what breaks if I change this"). Requires a prior codegraph_index.',
+    category: 'codegraph',
+    tags: ['code', 'imports', 'dependencies', 'impact', 'navigation'],
+    inputSchema: {
+        type: 'object',
+        properties: {
+            file: { type: 'string', description: 'Repo-relative file path whose importers you want' },
+            root: { type: 'string', description: 'Repo root (default: current working directory)' },
+        },
+        required: ['file'],
+    },
+    handler: async (params) => {
+        const root = rootOf(params);
+        const file = params.file;
+        if (typeof file !== 'string' || !file)
+            return { error: true, message: 'file is required' };
+        const index = loadIndex(root);
+        if (!index)
+            return { error: true, message: 'no index — run codegraph_index first' };
+        const edges = fileImporters(index, file);
+        return { file, count: edges.length, importers: edges };
+    },
+};
 export const codegraphTools = [
     codegraphIndexTool,
     codegraphQueryTool,
     codegraphFileTool,
+    codegraphImportsTool,
+    codegraphImportersTool,
     codegraphStatsTool,
 ];
 //# sourceMappingURL=codegraph-tools.js.map

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.10.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",