@yabasha/gex 0.3.2 → 0.4.0

package/README.md

@@ -55,15 +55,20 @@ Common options:
 Examples:
 
 ```bash
-# Local (default): JSON → stdout or to default file if -f provided without -o
-gex                  # same as: gex local
-gex -f md -o report.md
+# Local (default): JSON output to console
+gex                  # prints JSON to console (same as: gex local)
+gex -o report.json   # writes JSON to file
+gex -f md            # prints markdown to console
+gex -f md -o report.md  # writes markdown to file
 
 # Local: exclude devDependencies
-gex local --omit-dev -f json -o deps.json
+gex local --omit-dev    # prints JSON to console
+gex local --omit-dev -o deps.json  # writes JSON to file
 
 # Global packages
-gex global -f md -o global.md
+gex global              # prints JSON to console
+gex global -o global.json  # writes JSON to file
+gex global -f md        # prints markdown to console
 
 # Read a previous report (JSON or Markdown)
 # Default prints names@versions; add -i to install
@@ -74,8 +79,14 @@ gex read -r path/to/report.json -i
 # Markdown
 gex read global.md
 gex read global.md -i
+
+# Shell redirection (alternative to -o flag)
+gex > report.json           # redirect JSON output to file
+gex global | jq '.global_packages'  # pipe output to jq for processing
 ```
 
+> **Note**: Starting from v0.4.0, GEX outputs to console by default instead of creating files automatically. Use the `-o/--out-file` flag to write to a file.
+
 ## JSON schema (summary)
 
 Top-level keys:

package/dist/cli.cjs

@@ -34,23 +34,216 @@ __export(cli_exports, {
   run: () => run
 });
 module.exports = __toCommonJS(cli_exports);
-var import_promises2 = require("fs/promises");
-var import_node_path2 = __toESM(require("path"), 1);
-var import_node_url = require("url");
-var import_node_child_process2 = require("child_process");
-var import_node_util2 = require("util");
+
+// src/cli/commands.ts
+var import_node_path6 = __toESM(require("path"), 1);
 var import_commander = require("commander");
 
+// src/cli/install.ts
+async function getExecFileAsync() {
+  const { execFile } = await import("child_process");
+  const { promisify } = await import("util");
+  return promisify(execFile);
+}
+async function installFromReport(report, cwd) {
+  const globalPkgs = report.global_packages.map((p) => `${p.name}@${p.version}`).filter(Boolean);
+  const localPkgs = report.local_dependencies.map((p) => `${p.name}@${p.version}`).filter(Boolean);
+  const devPkgs = report.local_dev_dependencies.map((p) => `${p.name}@${p.version}`).filter(Boolean);
+  if (globalPkgs.length === 0 && localPkgs.length === 0 && devPkgs.length === 0) {
+    console.log("No packages to install from report.");
+    return;
+  }
+  const execFileAsync = await getExecFileAsync();
+  if (globalPkgs.length > 0) {
+    console.log(`Installing global: ${globalPkgs.join(" ")}`);
+    await execFileAsync("npm", ["i", "-g", ...globalPkgs], { cwd, maxBuffer: 10 * 1024 * 1024 });
+  }
+  if (localPkgs.length > 0) {
+    console.log(`Installing local deps: ${localPkgs.join(" ")}`);
+    await execFileAsync("npm", ["i", ...localPkgs], { cwd, maxBuffer: 10 * 1024 * 1024 });
+  }
+  if (devPkgs.length > 0) {
+    console.log(`Installing local devDeps: ${devPkgs.join(" ")}`);
+    await execFileAsync("npm", ["i", "-D", ...devPkgs], { cwd, maxBuffer: 10 * 1024 * 1024 });
+  }
+}
+function printFromReport(report) {
+  const lines = [];
+  if (report.global_packages.length > 0) {
+    lines.push("Global Packages:");
+    for (const p of report.global_packages) {
+      lines.push(`- ${p.name}@${p.version}`);
+    }
+  }
+  if (report.local_dependencies.length > 0) {
+    if (lines.length) lines.push("");
+    lines.push("Local Dependencies:");
+    for (const p of report.local_dependencies) {
+      lines.push(`- ${p.name}@${p.version}`);
+    }
+  }
+  if (report.local_dev_dependencies.length > 0) {
+    if (lines.length) lines.push("");
+    lines.push("Local Dev Dependencies:");
+    for (const p of report.local_dev_dependencies) {
+      lines.push(`- ${p.name}@${p.version}`);
+    }
+  }
+  if (lines.length === 0) {
+    lines.push("(no packages found in report)");
+  }
+  console.log(lines.join("\n"));
+}
+
+// src/cli/output.ts
+var import_node_path = __toESM(require("path"), 1);
+
+// src/report/json.ts
+function renderJson(report) {
+  const r = {
+    ...report,
+    global_packages: [...report.global_packages].sort((a, b) => a.name.localeCompare(b.name)),
+    local_dependencies: [...report.local_dependencies].sort((a, b) => a.name.localeCompare(b.name)),
+    local_dev_dependencies: [...report.local_dev_dependencies].sort(
+      (a, b) => a.name.localeCompare(b.name)
+    )
+  };
+  return JSON.stringify(r, null, 2);
+}
+
+// src/report/md.ts
+function table(headers, rows) {
+  const header = `| ${headers.join(" | ")} |`;
+  const sep = `| ${headers.map(() => "---").join(" | ")} |`;
+  const body = rows.map((r) => `| ${r.join(" | ")} |`).join("\n");
+  return [header, sep, body].filter(Boolean).join("\n");
+}
+function renderMarkdown(report) {
+  const lines = [];
+  lines.push("# GEX Report");
+  lines.push("");
+  if (report.project_name || report.project_version || report.project_description || report.project_homepage || report.project_bugs) {
+    lines.push("## Project Metadata");
+    if (report.project_name) lines.push(`- Name: ${report.project_name}`);
+    if (report.project_version) lines.push(`- Version: ${report.project_version}`);
+    if (report.project_description)
+      lines.push(`- Description: ${report.project_description}`);
+    if (report.project_homepage)
+      lines.push(`- Homepage: ${report.project_homepage}`);
+    if (report.project_bugs) lines.push(`- Bugs: ${report.project_bugs}`);
+    lines.push("");
+  }
+  if (report.global_packages.length > 0) {
+    lines.push("## Global Packages");
+    const rows = report.global_packages.map((p) => [p.name, p.version || "", p.resolved_path || ""]);
+    lines.push(table(["Name", "Version", "Path"], rows));
+    lines.push("");
+  }
+  if (report.local_dependencies.length > 0) {
+    lines.push("## Local Dependencies");
+    const rows = report.local_dependencies.map((p) => [
+      p.name,
+      p.version || "",
+      p.resolved_path || ""
+    ]);
+    lines.push(table(["Name", "Version", "Path"], rows));
+    lines.push("");
+  }
+  if (report.local_dev_dependencies.length > 0) {
+    lines.push("## Local Dev Dependencies");
+    const rows = report.local_dev_dependencies.map((p) => [
+      p.name,
+      p.version || "",
+      p.resolved_path || ""
+    ]);
+    lines.push(table(["Name", "Version", "Path"], rows));
+    lines.push("");
+  }
+  lines.push("---");
+  lines.push("_Generated by GEX_");
+  return lines.join("\n");
+}
+
+// src/cli/output.ts
+async function outputReport(report, format, outFile, markdownExtras) {
+  const content = format === "json" ? renderJson(report) : renderMarkdown({ ...report, ...markdownExtras || {} });
+  if (outFile) {
+    const outDir = import_node_path.default.dirname(outFile);
+    const { mkdir, writeFile } = await import("fs/promises");
+    await mkdir(outDir, { recursive: true });
+    await writeFile(outFile, content, "utf8");
+    console.log(`Wrote report to ${outFile}`);
+  } else {
+    console.log(content);
+  }
+}
+
+// src/cli/parser.ts
+var import_promises = require("fs/promises");
+var import_node_path2 = __toESM(require("path"), 1);
+function isMarkdownReportFile(filePath) {
+  const ext = import_node_path2.default.extname(filePath).toLowerCase();
+  return ext === ".md" || ext === ".markdown";
+}
+function parseMarkdownPackagesTable(lines, startIndex) {
+  const rows = [];
+  if (!lines[startIndex] || !lines[startIndex].trim().startsWith("|")) return rows;
+  let i = startIndex + 2;
+  while (i < lines.length && lines[i].trim().startsWith("|")) {
+    const cols = lines[i].split("|").map((c) => c.trim()).filter((_, idx, arr) => !(idx === 0 || idx === arr.length - 1));
+    const [name = "", version = "", resolved_path = ""] = cols;
+    if (name) rows.push({ name, version, resolved_path });
+    i++;
+  }
+  return rows;
+}
+function parseMarkdownReport(md) {
+  const lines = md.split(/\r?\n/);
+  const findSection = (title) => lines.findIndex((l) => l.trim().toLowerCase() === `## ${title}`.toLowerCase());
+  const parseSection = (idx) => {
+    if (idx < 0) return [];
+    let i = idx + 1;
+    while (i < lines.length && !lines[i].trim().startsWith("|")) i++;
+    return parseMarkdownPackagesTable(lines, i);
+  };
+  const global_packages = parseSection(findSection("Global Packages"));
+  const local_dependencies = parseSection(findSection("Local Dependencies"));
+  const local_dev_dependencies = parseSection(findSection("Local Dev Dependencies"));
+  const report = {
+    report_version: "1.0",
+    timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+    tool_version: "unknown",
+    global_packages,
+    local_dependencies,
+    local_dev_dependencies
+  };
+  return report;
+}
+async function loadReportFromFile(reportPath) {
+  const raw = await (0, import_promises.readFile)(reportPath, "utf8");
+  if (isMarkdownReportFile(reportPath) || raw.startsWith("# GEX Report")) {
+    return parseMarkdownReport(raw);
+  }
+  return JSON.parse(raw);
+}
+
+// src/cli/report.ts
+var import_promises4 = require("fs/promises");
+var import_node_path5 = __toESM(require("path"), 1);
+
 // src/npm.ts
-var import_node_child_process = require("child_process");
-var import_node_util = require("util");
-var execFileAsync = (0, import_node_util.promisify)(import_node_child_process.execFile);
+async function getExecFileAsync2() {
+  const { execFile } = await import("child_process");
+  const { promisify } = await import("util");
+  return promisify(execFile);
+}
 async function npmLs(options = {}) {
   const args = ["ls", "--json"];
   if (options.global) args.push("--global");
   if (options.omitDev) args.push("--omit=dev");
   if (options.depth0) args.push("--depth=0");
   try {
+    const execFileAsync = await getExecFileAsync2();
     const { stdout } = await execFileAsync("npm", args, {
       cwd: options.cwd,
       maxBuffer: 10 * 1024 * 1024
@@ -62,7 +255,10 @@ async function npmLs(options = {}) {
     if (typeof stdout === "string" && stdout.trim()) {
       try {
         return JSON.parse(stdout);
-      } catch {
+      } catch (parseErr) {
+        if (process.env.DEBUG?.includes("gex")) {
+          console.warn("npm ls stdout parse failed:", parseErr);
+        }
       }
     }
     const stderr = err?.stderr;
@@ -72,6 +268,7 @@ async function npmLs(options = {}) {
 }
 async function npmRootGlobal() {
   try {
+    const execFileAsync = await getExecFileAsync2();
     const { stdout } = await execFileAsync("npm", ["root", "-g"]);
     return stdout.trim();
   } catch (err) {
@@ -82,8 +279,8 @@ async function npmRootGlobal() {
 }
 
 // src/transform.ts
-var import_node_path = __toESM(require("path"), 1);
-var import_promises = require("fs/promises");
+var import_node_path3 = __toESM(require("path"), 1);
+var import_promises2 = require("fs/promises");
 function toPkgArray(obj) {
   if (!obj) return [];
   return Object.keys(obj).map((name) => ({ name, node: obj[name] })).filter((p) => p && p.node);
@@ -101,8 +298,8 @@ async function buildReportFromNpmTree(tree, opts) {
   if (opts.context === "local") {
     let pkgMeta = null;
     try {
-      const pkgJsonPath = import_node_path.default.join(opts.cwd || process.cwd(), "package.json");
-      const raw = await (0, import_promises.readFile)(pkgJsonPath, "utf8");
+      const pkgJsonPath = import_node_path3.default.join(opts.cwd || process.cwd(), "package.json");
+      const raw = await (0, import_promises2.readFile)(pkgJsonPath, "utf8");
       pkgMeta = JSON.parse(raw);
     } catch {
     }
@@ -113,7 +310,7 @@ async function buildReportFromNpmTree(tree, opts) {
     const devKeys = new Set(Object.keys(pkgMeta?.devDependencies || {}));
     for (const { name, node } of items) {
       const version = node && node.version || "";
-      const resolvedPath = node && node.path || import_node_path.default.join(opts.cwd || process.cwd(), "node_modules", name);
+      const resolvedPath = node && node.path || import_node_path3.default.join(opts.cwd || process.cwd(), "node_modules", name);
       const pkg = { name, version, resolved_path: resolvedPath };
       if (devKeys.has(name)) {
         report.local_dev_dependencies.push(pkg);
@@ -128,7 +325,7 @@ async function buildReportFromNpmTree(tree, opts) {
     const items = toPkgArray(depsObj);
     for (const { name, node } of items) {
       const version = node && node.version || "";
-      const resolvedPath = node && node.path || import_node_path.default.join(opts.globalRoot || "", name);
+      const resolvedPath = node && node.path || import_node_path3.default.join(opts.globalRoot || "", name);
       const pkg = { name, version, resolved_path: resolvedPath };
       report.global_packages.push(pkg);
     }
@@ -140,104 +337,42 @@ async function buildReportFromNpmTree(tree, opts) {
   return report;
 }
 
-// src/report/json.ts
-function renderJson(report) {
-  const r = {
-    ...report,
-    global_packages: [...report.global_packages].sort((a, b) => a.name.localeCompare(b.name)),
-    local_dependencies: [...report.local_dependencies].sort((a, b) => a.name.localeCompare(b.name)),
-    local_dev_dependencies: [...report.local_dev_dependencies].sort(
-      (a, b) => a.name.localeCompare(b.name)
-    )
-  };
-  return JSON.stringify(r, null, 2);
-}
-
-// src/report/md.ts
-function table(headers, rows) {
-  const header = `| ${headers.join(" | ")} |`;
-  const sep = `| ${headers.map(() => "---").join(" | ")} |`;
-  const body = rows.map((r) => `| ${r.join(" | ")} |`).join("\n");
-  return [header, sep, body].filter(Boolean).join("\n");
-}
-function renderMarkdown(report) {
-  const lines = [];
-  lines.push("# GEX Report");
-  lines.push("");
-  if (report.project_name || report.project_version) {
-    lines.push("## Project Metadata");
-    if (report.project_name) lines.push(`- Name: ${report.project_name}`);
-    if (report.project_version) lines.push(`- Version: ${report.project_version}`);
-    if (report.project_description)
-      lines.push(`- Description: ${report.project_description}`);
-    if (report.project_homepage)
-      lines.push(`- Homepage: ${report.project_homepage}`);
-    if (report.project_bugs) lines.push(`- Bugs: ${report.project_bugs}`);
-    lines.push("");
-  }
-  if (report.global_packages.length > 0) {
-    lines.push("## Global Packages");
-    const rows = report.global_packages.map((p) => [p.name, p.version || "", p.resolved_path || ""]);
-    lines.push(table(["Name", "Version", "Path"], rows));
-    lines.push("");
-  }
-  if (report.local_dependencies.length > 0) {
-    lines.push("## Local Dependencies");
-    const rows = report.local_dependencies.map((p) => [
-      p.name,
-      p.version || "",
-      p.resolved_path || ""
-    ]);
-    lines.push(table(["Name", "Version", "Path"], rows));
-    lines.push("");
-  }
-  if (report.local_dev_dependencies.length > 0) {
-    lines.push("## Local Dev Dependencies");
-    const rows = report.local_dev_dependencies.map((p) => [
-      p.name,
-      p.version || "",
-      p.resolved_path || ""
-    ]);
-    lines.push(table(["Name", "Version", "Path"], rows));
-    lines.push("");
-  }
-  lines.push("---");
-  lines.push("_Generated by GEX_");
-  return lines.join("\n");
-}
-
-// src/cli.ts
+// src/cli/utils.ts
+var import_promises3 = require("fs/promises");
+var import_node_path4 = __toESM(require("path"), 1);
+var import_node_url = require("url");
 var import_meta = {};
 function getPkgJsonPath() {
   try {
     const __filename = (0, import_node_url.fileURLToPath)(import_meta.url);
-    const __dirnameLocal = import_node_path2.default.dirname(__filename);
-    return import_node_path2.default.resolve(__dirnameLocal, "..", "package.json");
+    const __dirnameLocal = import_node_path4.default.dirname(__filename);
+    return import_node_path4.default.resolve(__dirnameLocal, "..", "..", "package.json");
   } catch {
     const dir = typeof __dirname !== "undefined" ? __dirname : process.cwd();
-    return import_node_path2.default.resolve(dir, "..", "package.json");
+    return import_node_path4.default.resolve(dir, "..", "package.json");
   }
 }
 async function getToolVersion() {
   try {
     const pkgPath = getPkgJsonPath();
-    const raw = await (0, import_promises2.readFile)(pkgPath, "utf8");
+    const raw = await (0, import_promises3.readFile)(pkgPath, "utf8");
     const pkg = JSON.parse(raw);
     return pkg.version || "0.0.0";
   } catch {
     return "0.0.0";
   }
 }
-var execFileAsync2 = (0, import_node_util2.promisify)(import_node_child_process2.execFile);
 var ASCII_BANNER = String.raw`
   ________                __
- /  _____/  ____   _____/  |_  ____   ____ 
+ /  _____/  ____   _____/  |_  ____   ____
 /   \  ___ /  _ \ /  _ \   __\/ __ \ /    \
 \    \_\  (  <_> |  <_> )  | \  ___/|   |  \
  \______  /\____/ \____/|__|  \___  >___|  /
-        \/                         \/     \/ 
+        \/                         \/     \/
                       GEX
 `;
+
+// src/cli/report.ts
 async function produceReport(ctx, options) {
   const toolVersion = await getToolVersion();
   const depth0 = !options.fullTree;
@@ -253,7 +388,7 @@ async function produceReport(ctx, options) {
   let project_bugs;
   if (ctx === "local") {
     try {
-      const pkgRaw = await (0, import_promises2.readFile)(import_node_path2.default.join(cwd, "package.json"), "utf8");
+      const pkgRaw = await (0, import_promises4.readFile)(import_node_path5.default.join(cwd, "package.json"), "utf8");
       const pkg = JSON.parse(pkgRaw);
       project_description = pkg.description;
       project_homepage = pkg.homepage;
@@ -274,126 +409,21 @@ async function produceReport(ctx, options) {
   const markdownExtras = { project_description, project_homepage, project_bugs };
   return { report, markdownExtras };
 }
-function printFromReport(report) {
-  const lines = [];
-  if (report.global_packages.length > 0) {
-    lines.push("Global Packages:");
-    for (const p of report.global_packages) {
-      lines.push(`- ${p.name}@${p.version}`);
-    }
-  }
-  if (report.local_dependencies.length > 0) {
-    if (lines.length) lines.push("");
-    lines.push("Local Dependencies:");
-    for (const p of report.local_dependencies) {
-      lines.push(`- ${p.name}@${p.version}`);
-    }
-  }
-  if (report.local_dev_dependencies.length > 0) {
-    if (lines.length) lines.push("");
-    lines.push("Local Dev Dependencies:");
-    for (const p of report.local_dev_dependencies) {
-      lines.push(`- ${p.name}@${p.version}`);
-    }
-  }
-  if (lines.length === 0) {
-    lines.push("(no packages found in report)");
-  }
-  console.log(lines.join("\n"));
-}
-async function installFromReport(report, cwd) {
-  const globalPkgs = report.global_packages.map((p) => `${p.name}@${p.version}`).filter(Boolean);
-  const localPkgs = report.local_dependencies.map((p) => `${p.name}@${p.version}`).filter(Boolean);
-  const devPkgs = report.local_dev_dependencies.map((p) => `${p.name}@${p.version}`).filter(Boolean);
-  if (globalPkgs.length === 0 && localPkgs.length === 0 && devPkgs.length === 0) {
-    console.log("No packages to install from report.");
-    return;
-  }
-  if (globalPkgs.length > 0) {
-    console.log(`Installing global: ${globalPkgs.join(" ")}`);
-    await execFileAsync2("npm", ["i", "-g", ...globalPkgs], { cwd, maxBuffer: 10 * 1024 * 1024 });
-  }
-  if (localPkgs.length > 0) {
-    console.log(`Installing local deps: ${localPkgs.join(" ")}`);
-    await execFileAsync2("npm", ["i", ...localPkgs], { cwd, maxBuffer: 10 * 1024 * 1024 });
-  }
-  if (devPkgs.length > 0) {
-    console.log(`Installing local devDeps: ${devPkgs.join(" ")}`);
-    await execFileAsync2("npm", ["i", "-D", ...devPkgs], { cwd, maxBuffer: 10 * 1024 * 1024 });
-  }
-}
-async function outputReport(report, format, outFile, markdownExtras) {
-  const content = format === "json" ? renderJson(report) : renderMarkdown({ ...report, ...markdownExtras || {} });
-  if (outFile) {
-    const outDir = import_node_path2.default.dirname(outFile);
-    await (await import("fs/promises")).mkdir(outDir, { recursive: true });
-    await (await import("fs/promises")).writeFile(outFile, content, "utf8");
-    console.log(`Wrote report to ${outFile}`);
-  } else {
-    console.log(content);
-  }
-}
-function isMarkdownReportFile(filePath) {
-  const ext = import_node_path2.default.extname(filePath).toLowerCase();
-  return ext === ".md" || ext === ".markdown";
-}
-function parseMarkdownPackagesTable(lines, startIndex) {
-  const rows = [];
-  if (!lines[startIndex] || !lines[startIndex].trim().startsWith("|")) return rows;
-  let i = startIndex + 2;
-  while (i < lines.length && lines[i].trim().startsWith("|")) {
-    const cols = lines[i].split("|").map((c) => c.trim()).filter((_, idx, arr) => !(idx === 0 || idx === arr.length - 1));
-    const [name = "", version = "", resolved_path = ""] = cols;
-    if (name) rows.push({ name, version, resolved_path });
-    i++;
-  }
-  return rows;
-}
-function parseMarkdownReport(md) {
-  const lines = md.split(/\r?\n/);
-  const findSection = (title) => lines.findIndex((l) => l.trim().toLowerCase() === `## ${title}`.toLowerCase());
-  const parseSection = (idx) => {
-    if (idx < 0) return [];
-    let i = idx + 1;
-    while (i < lines.length && !lines[i].trim().startsWith("|")) i++;
-    return parseMarkdownPackagesTable(lines, i);
-  };
-  const global_packages = parseSection(findSection("Global Packages"));
-  const local_dependencies = parseSection(findSection("Local Dependencies"));
-  const local_dev_dependencies = parseSection(findSection("Local Dev Dependencies"));
-  const report = {
-    report_version: "1.0",
-    timestamp: (/* @__PURE__ */ new Date()).toISOString(),
-    tool_version: "unknown",
-    global_packages,
-    local_dependencies,
-    local_dev_dependencies
-  };
-  return report;
-}
-async function loadReportFromFile(reportPath) {
-  const raw = await (0, import_promises2.readFile)(reportPath, "utf8");
-  if (isMarkdownReportFile(reportPath) || raw.startsWith("# GEX Report")) {
-    return parseMarkdownReport(raw);
+
+// src/cli/commands.ts
+function addCommonOptions(cmd, { allowOmitDev }) {
+  cmd.option(
+    "-f, --output-format <format>",
+    "Output format: md or json",
+    (val) => val === "md" ? "md" : "json",
+    "json"
+  ).option("-o, --out-file <path>", "Write report to file").option("--full-tree", "Include full npm ls tree (omit depth=0 default)", false);
+  if (allowOmitDev) {
+    cmd.option("--omit-dev", "Exclude devDependencies (local only)", false);
   }
-  return JSON.parse(raw);
+  return cmd;
 }
-async function run(argv = process.argv) {
-  const program = new import_commander.Command().name("gex").description("GEX: Dependency auditing and documentation for Node.js (local and global).").version(await getToolVersion());
-  program.addHelpText("beforeAll", `
-${ASCII_BANNER}`);
-  const addCommonOptions = (cmd, { allowOmitDev }) => {
-    cmd.option(
-      "-f, --output-format <format>",
-      "Output format: md or json",
-      (val) => val === "md" ? "md" : "json",
-      "json"
-    ).option("-o, --out-file <path>", "Write report to file").option("--full-tree", "Include full npm ls tree (omit depth=0 default)", false);
-    if (allowOmitDev) {
-      cmd.option("--omit-dev", "Exclude devDependencies (local only)", false);
-    }
-    return cmd;
-  };
+function createLocalCommand(program) {
   const localCmd = program.command("local", { isDefault: true }).description("Generate a report for the current project's dependencies");
   addCommonOptions(localCmd, { allowOmitDev: true });
   localCmd.action(async (opts) => {
@@ -401,10 +431,7 @@ ${ASCII_BANNER}`);
     const outFile = opts.outFile;
     const fullTree = Boolean(opts.fullTree);
     const omitDev = Boolean(opts.omitDev);
-    let finalOutFile = outFile;
-    if (!outFile && opts.outputFormat && typeof opts.outputFormat === "string") {
-      finalOutFile = `gex-report.${outputFormat}`;
-    }
+    const finalOutFile = outFile;
     const { report, markdownExtras } = await produceReport("local", {
       outputFormat,
       outFile: finalOutFile,
@@ -413,16 +440,16 @@ ${ASCII_BANNER}`);
     });
     await outputReport(report, outputFormat, finalOutFile, markdownExtras);
   });
+  return localCmd;
+}
+function createGlobalCommand(program) {
   const globalCmd = program.command("global").description("Generate a report of globally installed packages");
   addCommonOptions(globalCmd, { allowOmitDev: false });
   globalCmd.action(async (opts) => {
     const outputFormat = opts.outputFormat ?? "json";
     const outFile = opts.outFile;
     const fullTree = Boolean(opts.fullTree);
-    let finalOutFile = outFile;
-    if (!outFile && opts.outputFormat && typeof opts.outputFormat === "string") {
-      finalOutFile = `gex-report.${outputFormat}`;
-    }
+    const finalOutFile = outFile;
     const { report, markdownExtras } = await produceReport("global", {
       outputFormat,
       outFile: finalOutFile,
@@ -430,12 +457,15 @@ ${ASCII_BANNER}`);
     });
     await outputReport(report, outputFormat, finalOutFile, markdownExtras);
   });
+  return globalCmd;
+}
+function createReadCommand(program) {
   const readCmd = program.command("read").description(
     "Read a previously generated report (JSON or Markdown) and either print package names or install them"
   ).argument("[report]", "Path to report file (JSON or Markdown)", "gex-report.json").option("-r, --report <path>", "Path to report file (JSON or Markdown)").option("-p, --print", "Print package names/versions from the report (default)", false).option("-i, --install", "Install packages from the report", false);
   readCmd.action(async (reportArg, opts) => {
     const chosen = opts.report || reportArg || "gex-report.json";
-    const reportPath = import_node_path2.default.resolve(process.cwd(), chosen);
+    const reportPath = import_node_path6.default.resolve(process.cwd(), chosen);
     try {
       const parsed = await loadReportFromFile(reportPath);
       const doInstall = Boolean(opts.install);
@@ -454,12 +484,42 @@ ${ASCII_BANNER}`);
       process.exitCode = 1;
     }
   });
+  return readCmd;
+}
+async function createProgram() {
+  const program = new import_commander.Command().name("gex").description("GEX: Dependency auditing and documentation for Node.js (local and global).").version(await getToolVersion());
+  program.addHelpText("beforeAll", `
+${ASCII_BANNER}`);
+  createLocalCommand(program);
+  createGlobalCommand(program);
+  createReadCommand(program);
+  return program;
+}
+
+// src/cli.ts
+var import_meta2 = {};
+async function run(argv = process.argv) {
+  const program = await createProgram();
   await program.parseAsync(argv);
 }
-var isCjsMain = typeof require !== "undefined" && require.main === module;
-var isEsmMain = typeof import_meta !== "undefined" && import_meta.url === `file://${process.argv[1]}`;
-if (isCjsMain || isEsmMain) {
-  run();
+var isMainModule = (() => {
+  try {
+    if (typeof require !== "undefined" && typeof module !== "undefined") {
+      return require.main === module;
+    }
+    if (typeof import_meta2 !== "undefined") {
+      return import_meta2.url === `file://${process.argv[1]}`;
+    }
+    return false;
+  } catch {
+    return false;
+  }
+})();
+if (isMainModule) {
+  run().catch((error) => {
+    console.error("CLI error:", error);
+    process.exitCode = 1;
+  });
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {