frontmcp 1.0.0 → 1.0.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "frontmcp",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "FrontMCP command line interface",
   "author": "AgentFront <info@agentfront.dev>",
   "homepage": "https://docs.agentfront.dev",
@@ -30,7 +30,7 @@
   },
   "dependencies": {
     "@clack/prompts": "^0.10.0",
-    "@frontmcp/utils": "1.0.0",
+    "@frontmcp/utils": "1.0.2",
     "commander": "^13.0.0",
     "tslib": "^2.3.0",
     "vectoriadb": "^2.1.3",

package/src/commands/build/exec/cli-runtime/cli-bundler.js

@@ -31,6 +31,7 @@ async function bundleCliWithEsbuild(cliEntryPath, outDir, config, options) {
             // Only true native addons and optional peer deps stay external in self-contained mode
             'better-sqlite3',
             'fsevents',
+            'esbuild',
             '@vercel/kv',
             '@frontmcp/storage-sqlite',
             '@enclave-vm/core',
@@ -41,6 +42,7 @@ async function bundleCliWithEsbuild(cliEntryPath, outDir, config, options) {
             '@frontmcp/sdk',
             'better-sqlite3',
             'fsevents',
+            'esbuild',
             '@vercel/kv',
             '@frontmcp/storage-sqlite',
             '@enclave-vm/core',

package/src/commands/build/exec/cli-runtime/cli-bundler.js.map

@@ -1 +1 @@
-{"version":3,"file":"cli-bundler.js","sourceRoot":"","sources":["../../../../../../src/commands/build/exec/cli-runtime/cli-bundler.ts"],"names":[],"mappings":";AAAA;;;GAGG;;AAeH,oDAuEC;;AApFD,mDAA6B;AAQ7B;;;;GAIG;AACI,KAAK,UAAU,oBAAoB,CACxC,YAAoB,EACpB,MAAc,EACd,MAA0B,EAC1B,OAAqC;IAErC,IAAI,OAAiC,CAAC;IACtC,IAAI,CAAC;QACH,OAAO,GAAG,OAAO,CAAC,SAAS,CAAC,CAAC;IAC/B,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,IAAI,KAAK,CACb,wEAAwE,CACzE,CAAC;IACJ,CAAC;IAED,MAAM,aAAa,GAAG,GAAG,MAAM,CAAC,IAAI,gBAAgB,CAAC;IACrD,MAAM,UAAU,GAAG,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;IACpD,MAAM,aAAa,GAAG,OAAO,EAAE,aAAa,IAAI,KAAK,CAAC;IAEtD,uEAAuE;IACvE,gEAAgE;IAChE,MAAM,gBAAgB,GAAG,GAAG,MAAM,CAAC,IAAI,YAAY,CAAC;IAEpD,MAAM,QAAQ,GAAG,aAAa;QAC5B,CAAC,CAAC;YACE,sFAAsF;YACtF,gBAAgB;YAChB,UAAU;YACV,YAAY;YACZ,0BAA0B;YAC1B,kBAAkB;YAClB,GAAG,CAAC,MAAM,CAAC,YAAY,EAAE,YAAY,IAAI,EAAE,CAAC;SAC7C;QACH,CAAC,CAAC;YACE,KAAK,gBAAgB,EAAE;YACvB,eAAe;YACf,gBAAgB;YAChB,UAAU;YACV,YAAY;YACZ,0BAA0B;YAC1B,kBAAkB;YAClB,GAAG,CAAC,MAAM,CAAC,YAAY,EAAE,YAAY,IAAI,EAAE,CAAC;YAC5C,GAAG,CAAC,MAAM,CAAC,OAAO,EAAE,QAAQ,IAAI,EAAE,CAAC;SACpC,CAAC;IAEN,MAAM,OAAO,CAAC,KAAK,CAAC;QAClB,WAAW,EAAE,CAAC,YAAY,CAAC;QAC3B,MAAM,EAAE,IAAI;QACZ,QAAQ,EAAE,MAAM;QAChB,MAAM,EAAE,KAAK;QACb,MAAM,EAAE,MAAM,CAAC,OAAO,EAAE,MAAM,IAAI,QAAQ;QAC1C,OAAO,EAAE,UAAU;QACnB,QAAQ;QACR,SAAS,EAAE,IAAI;QACf,WAAW,EAAE,IAAI;QACjB,MAAM,EAAE,MAAM,CAAC,OAAO,EAAE,MAAM,IAAI,KAAK;QACvC,MAAM,EAAE;YACN,EAAE,EAAE,qBAAqB;SAC1B;QACD,MAAM,EAAE,MAAM,CAAC,OAAO,EAAE,MAAM;QAC9B,SAAS,EAAE,KAAK;QAChB,QAAQ,EAAE,SAAS;KACpB,CAAC,CAAC;IAEH,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACzB,MAAM,IAAI,GAAG,EAAE,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAC;IAErC,OAAO;QACL,UAAU;QACV,UAAU,EAAE,IAAI,CAAC,IAAI;KACtB,CAAC;AACJ,CAAC","sourcesContent":["/**\n * esbuild configuration for the CLI bundle.\n * Bundles the generated CLI entry point with commander.js inlined.\n */\n\nimport * as path from 'path';\nimport { FrontmcpExecConfig } from '../config';\n\nexport interface CliBundleResult {\n  bundlePath: string;\n  bundleSize: number;\n}\n\n/**\n * Bundle the generated CLI entry with esbuild.\n * Commander.js and runtime modules are inlined; the server bundle is external\n * unless selfContained mode is enabled (for SEA builds).\n */\nexport async function bundleCliWithEsbuild(\n  cliEntryPath: string,\n  outDir: string,\n  config: FrontmcpExecConfig,\n  options?: { selfContained?: boolean },\n): Promise<CliBundleResult> {\n  let esbuild: typeof import('esbuild');\n  try {\n    esbuild = require('esbuild');\n  } catch {\n    throw new Error(\n      'esbuild is required for CLI builds. Install it: npm install -D esbuild',\n    );\n  }\n\n  const cliBundleName = `${config.name}-cli.bundle.js`;\n  const bundlePath = path.join(outDir, cliBundleName);\n  const selfContained = options?.selfContained ?? false;\n\n  // The server bundle is loaded via require() at runtime — keep external\n  // unless selfContained mode where everything is inlined for SEA\n  const serverBundleName = `${config.name}.bundle.js`;\n\n  const external = selfContained\n    ? [\n        // Only true native addons and optional peer deps stay external in self-contained mode\n        'better-sqlite3',\n        'fsevents',\n        '@vercel/kv',\n        '@frontmcp/storage-sqlite',\n        '@enclave-vm/core',\n        ...(config.dependencies?.nativeAddons || []),\n      ]\n    : [\n        `./${serverBundleName}`,\n        '@frontmcp/sdk',\n        'better-sqlite3',\n        'fsevents',\n        '@vercel/kv',\n        '@frontmcp/storage-sqlite',\n        '@enclave-vm/core',\n        ...(config.dependencies?.nativeAddons || []),\n        ...(config.esbuild?.external || []),\n      ];\n\n  await esbuild.build({\n    entryPoints: [cliEntryPath],\n    bundle: true,\n    platform: 'node',\n    format: 'cjs',\n    target: config.esbuild?.target || 'node22',\n    outfile: bundlePath,\n    external,\n    keepNames: true,\n    treeShaking: true,\n    minify: config.esbuild?.minify ?? false,\n    banner: {\n      js: '#!/usr/bin/env node',\n    },\n    define: config.esbuild?.define,\n    sourcemap: false,\n    logLevel: 'warning',\n  });\n\n  const fs = require('fs');\n  const stat = fs.statSync(bundlePath);\n\n  return {\n    bundlePath,\n    bundleSize: stat.size,\n  };\n}\n"]}
+{"version":3,"file":"cli-bundler.js","sourceRoot":"","sources":["../../../../../../src/commands/build/exec/cli-runtime/cli-bundler.ts"],"names":[],"mappings":";AAAA;;;GAGG;;AAeH,oDAyEC;;AAtFD,mDAA6B;AAQ7B;;;;GAIG;AACI,KAAK,UAAU,oBAAoB,CACxC,YAAoB,EACpB,MAAc,EACd,MAA0B,EAC1B,OAAqC;IAErC,IAAI,OAAiC,CAAC;IACtC,IAAI,CAAC;QACH,OAAO,GAAG,OAAO,CAAC,SAAS,CAAC,CAAC;IAC/B,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,IAAI,KAAK,CACb,wEAAwE,CACzE,CAAC;IACJ,CAAC;IAED,MAAM,aAAa,GAAG,GAAG,MAAM,CAAC,IAAI,gBAAgB,CAAC;IACrD,MAAM,UAAU,GAAG,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;IACpD,MAAM,aAAa,GAAG,OAAO,EAAE,aAAa,IAAI,KAAK,CAAC;IAEtD,uEAAuE;IACvE,gEAAgE;IAChE,MAAM,gBAAgB,GAAG,GAAG,MAAM,CAAC,IAAI,YAAY,CAAC;IAEpD,MAAM,QAAQ,GAAG,aAAa;QAC5B,CAAC,CAAC;YACE,sFAAsF;YACtF,gBAAgB;YAChB,UAAU;YACV,SAAS;YACT,YAAY;YACZ,0BAA0B;YAC1B,kBAAkB;YAClB,GAAG,CAAC,MAAM,CAAC,YAAY,EAAE,YAAY,IAAI,EAAE,CAAC;SAC7C;QACH,CAAC,CAAC;YACE,KAAK,gBAAgB,EAAE;YACvB,eAAe;YACf,gBAAgB;YAChB,UAAU;YACV,SAAS;YACT,YAAY;YACZ,0BAA0B;YAC1B,kBAAkB;YAClB,GAAG,CAAC,MAAM,CAAC,YAAY,EAAE,YAAY,IAAI,EAAE,CAAC;YAC5C,GAAG,CAAC,MAAM,CAAC,OAAO,EAAE,QAAQ,IAAI,EAAE,CAAC;SACpC,CAAC;IAEN,MAAM,OAAO,CAAC,KAAK,CAAC;QAClB,WAAW,EAAE,CAAC,YAAY,CAAC;QAC3B,MAAM,EAAE,IAAI;QACZ,QAAQ,EAAE,MAAM;QAChB,MAAM,EAAE,KAAK;QACb,MAAM,EAAE,MAAM,CAAC,OAAO,EAAE,MAAM,IAAI,QAAQ;QAC1C,OAAO,EAAE,UAAU;QACnB,QAAQ;QACR,SAAS,EAAE,IAAI;QACf,WAAW,EAAE,IAAI;QACjB,MAAM,EAAE,MAAM,CAAC,OAAO,EAAE,MAAM,IAAI,KAAK;QACvC,MAAM,EAAE;YACN,EAAE,EAAE,qBAAqB;SAC1B;QACD,MAAM,EAAE,MAAM,CAAC,OAAO,EAAE,MAAM;QAC9B,SAAS,EAAE,KAAK;QAChB,QAAQ,EAAE,SAAS;KACpB,CAAC,CAAC;IAEH,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACzB,MAAM,IAAI,GAAG,EAAE,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAC;IAErC,OAAO;QACL,UAAU;QACV,UAAU,EAAE,IAAI,CAAC,IAAI;KACtB,CAAC;AACJ,CAAC","sourcesContent":["/**\n * esbuild configuration for the CLI bundle.\n * Bundles the generated CLI entry point with commander.js inlined.\n */\n\nimport * as path from 'path';\nimport { FrontmcpExecConfig } from '../config';\n\nexport interface CliBundleResult {\n  bundlePath: string;\n  bundleSize: number;\n}\n\n/**\n * Bundle the generated CLI entry with esbuild.\n * Commander.js and runtime modules are inlined; the server bundle is external\n * unless selfContained mode is enabled (for SEA builds).\n */\nexport async function bundleCliWithEsbuild(\n  cliEntryPath: string,\n  outDir: string,\n  config: FrontmcpExecConfig,\n  options?: { selfContained?: boolean },\n): Promise<CliBundleResult> {\n  let esbuild: typeof import('esbuild');\n  try {\n    esbuild = require('esbuild');\n  } catch {\n    throw new Error(\n      'esbuild is required for CLI builds. Install it: npm install -D esbuild',\n    );\n  }\n\n  const cliBundleName = `${config.name}-cli.bundle.js`;\n  const bundlePath = path.join(outDir, cliBundleName);\n  const selfContained = options?.selfContained ?? false;\n\n  // The server bundle is loaded via require() at runtime — keep external\n  // unless selfContained mode where everything is inlined for SEA\n  const serverBundleName = `${config.name}.bundle.js`;\n\n  const external = selfContained\n    ? [\n        // Only true native addons and optional peer deps stay external in self-contained mode\n        'better-sqlite3',\n        'fsevents',\n        'esbuild',\n        '@vercel/kv',\n        '@frontmcp/storage-sqlite',\n        '@enclave-vm/core',\n        ...(config.dependencies?.nativeAddons || []),\n      ]\n    : [\n        `./${serverBundleName}`,\n        '@frontmcp/sdk',\n        'better-sqlite3',\n        'fsevents',\n        'esbuild',\n        '@vercel/kv',\n        '@frontmcp/storage-sqlite',\n        '@enclave-vm/core',\n        ...(config.dependencies?.nativeAddons || []),\n        ...(config.esbuild?.external || []),\n      ];\n\n  await esbuild.build({\n    entryPoints: [cliEntryPath],\n    bundle: true,\n    platform: 'node',\n    format: 'cjs',\n    target: config.esbuild?.target || 'node22',\n    outfile: bundlePath,\n    external,\n    keepNames: true,\n    treeShaking: true,\n    minify: config.esbuild?.minify ?? false,\n    banner: {\n      js: '#!/usr/bin/env node',\n    },\n    define: config.esbuild?.define,\n    sourcemap: false,\n    logLevel: 'warning',\n  });\n\n  const fs = require('fs');\n  const stat = fs.statSync(bundlePath);\n\n  return {\n    bundlePath,\n    bundleSize: stat.size,\n  };\n}\n"]}

package/src/commands/build/exec/cli-runtime/generate-cli-entry.js

@@ -110,6 +110,8 @@ ${hasOAuth ? "var oauthHelper = require('./oauth-helper');" : ''}
 var APP_NAME = ${JSON.stringify(appName)};
 var SCRIPT_DIR = __dirname;
 var FRONTMCP_HOME = process.env.FRONTMCP_HOME || path.join(os.homedir(), '.frontmcp');
+// Set app name for file logger (writes to ~/.frontmcp/logs/{appName}-{timestamp}.log)
+process.env.FRONTMCP_APP_NAME = process.env.FRONTMCP_APP_NAME || APP_NAME;
 ${selfContained
         ? `// Self-contained: server bundle and SDK are inlined by esbuild
 var SERVER_BUNDLE = '../${serverBundleFilename}';`
@@ -132,7 +134,10 @@ async function getClient() {
   }
 
   // Fallback: in-process connect (with CLI mode for faster init)
+  // Suppress @FrontMcp decorator bootstrap — we only need config metadata, not a running server.
+  process.env.FRONTMCP_SCHEMA_EXTRACT = '1';
   var mod = require(${selfContained ? `'../${serverBundleFilename}'` : 'SERVER_BUNDLE'});
+  delete process.env.FRONTMCP_SCHEMA_EXTRACT;
   var configOrClass = mod.default || mod;
   var sdk = require('@frontmcp/sdk');
   var connect = sdk.connect || sdk.direct.connect;${authRequired ? `
@@ -145,12 +150,37 @@ async function getClient() {
   return _client;
 }
 
+async function closeClient() {
+  if (_client && typeof _client.close === 'function') {
+    try { await _client.close(); } catch (_) {}
+  }
+  _client = null;
+}
+
+// Flag set by long-running commands (serve, daemon) to prevent the footer from calling process.exit().
+var _isLongRunning = false;
+
 var program = new Command();
 program
   .name(${JSON.stringify(appName)})
   .version(${JSON.stringify(appVersion)})
   .description(${JSON.stringify(description || `${appName} CLI`)})
-  .option('--output <mode>', 'Output format: text or json', ${JSON.stringify(outputDefault)});
+  .option('--output <mode>', 'Output format: text or json', ${JSON.stringify(outputDefault)})
+  .option('--verbose', 'Enable verbose console logging (logs always go to ~/.frontmcp/logs/)')
+  .option('--log-dir <path>', 'Directory for log files (default: ~/.frontmcp/logs/)');
+
+// Wire --verbose and --log-dir to env vars early (before any command action runs).
+// Parse argv directly since commander hooks may not be available in all versions.
+(function() {
+  var argv = process.argv;
+  if (argv.indexOf('--verbose') !== -1) {
+    process.env.FRONTMCP_CLI_VERBOSE = '1';
+  }
+  var logDirIdx = argv.indexOf('--log-dir');
+  if (logDirIdx !== -1 && argv[logDirIdx + 1]) {
+    process.env.FRONTMCP_LOG_DIR = argv[logDirIdx + 1];
+  }
+})();
 
 program.configureHelp({
   sortSubcommands: false,
@@ -456,15 +486,20 @@ skillsCmd
       if (mode === 'json') {
         console.log(JSON.stringify(result, null, 2));
       } else {
-        var skills = result.skills || result || [];
-        if (Array.isArray(skills) && skills.length === 0) { console.log('No skills found.'); return; }
-        if (Array.isArray(skills)) {
-          skills.forEach(function(s) {
-            console.log('  ' + (s.name || s.id || JSON.stringify(s)));
-          });
-        } else {
-          console.log(JSON.stringify(result, null, 2));
-        }
+        var skills = result.skills || [];
+        if (skills.length === 0) { console.log('No skills found.'); return; }
+        console.log('\\n  Skills matching "' + (query || '') + '":\\n');
+        skills.forEach(function(s) {
+          var tags = (s.tags || []).slice(0, 3).join(', ');
+          var score = s.score != null ? ' [score: ' + Number(s.score).toFixed(2) + ']' : '';
+          console.log('  ' + (s.name || s.id) + score);
+          if (s.description) console.log('    ' + s.description.split('. Use when')[0]);
+          if (tags) console.log('    tags: ' + tags);
+          console.log('');
+        });
+        console.log('  ' + skills.length + ' result(s).');
+        console.log("  Use '" + program.name() + " skills read <name>' for full details.");
+        console.log("  Use '" + program.name() + " skills load <name>' to load a skill.\\n");
       }
     } catch (err) {
       console.error('Error:', err.message || err);
@@ -494,6 +529,43 @@ skillsCmd
     }
   });
 
+skillsCmd
+  .command('read <name>')
+  .description('Read full details for a skill')
+  .action(async function(name) {
+    try {
+      var client = await getClient();
+      var result = await client.loadSkills([name]);
+      var mode = program.opts().output || 'text';
+      if (mode === 'json') {
+        console.log(JSON.stringify(result, null, 2));
+      } else {
+        var skills = result.skills || [];
+        if (skills.length === 0) { console.log('Skill "' + name + '" not found.'); return; }
+        var sk = skills[0];
+        console.log('\\n  ' + sk.name);
+        if (sk.description) console.log('  ' + sk.description);
+        console.log('');
+        if (sk.instructions) {
+          console.log(sk.instructions);
+          console.log('');
+        }
+        if (sk.tools && sk.tools.length > 0) {
+          console.log('  Tools (' + sk.tools.length + '):');
+          sk.tools.forEach(function(t) {
+            console.log('    ' + t.name + (t.available ? '' : ' (unavailable)'));
+          });
+          console.log('');
+        }
+        if (result.nextSteps) console.log('  ' + result.nextSteps);
+        console.log("  Load: " + program.name() + " skills load " + name + '\\n');
+      }
+    } catch (err) {
+      console.error('Error:', err.message || err);
+      process.exitCode = 1;
+    }
+  });
+
 skillsCmd
   .command('list')
   .description('List available skills')
@@ -505,15 +577,17 @@ skillsCmd
       if (mode === 'json') {
         console.log(JSON.stringify(result, null, 2));
       } else {
-        var skills = result.skills || result || [];
-        if (Array.isArray(skills) && skills.length === 0) { console.log('No skills available.'); return; }
-        if (Array.isArray(skills)) {
-          skills.forEach(function(s) {
-            console.log('  ' + (s.name || s.id || JSON.stringify(s)));
-          });
-        } else {
-          console.log(JSON.stringify(result, null, 2));
-        }
+        var skills = result.skills || [];
+        if (skills.length === 0) { console.log('No skills available.'); return; }
+        console.log('\\n  Available Skills (' + skills.length + '):\\n');
+        skills.forEach(function(s) {
+          var desc = s.description ? s.description.split('. Use when')[0] : '';
+          console.log('  ' + (s.name || s.id));
+          if (desc) console.log('    ' + desc);
+          console.log('');
+        });
+        console.log("  Use '" + program.name() + " skills search <query>' for semantic search.");
+        console.log("  Use '" + program.name() + " skills read <name>' for full details.\\n");
       }
     } catch (err) {
       console.error('Error:', err.message || err);
@@ -787,7 +861,9 @@ async function getSubscribeClient() {
   // If connected via daemon, the onNotification/onResourceUpdated are no-ops.
   // Reconnect via in-process for push support.
   if (client._isDaemon) {
-    _client = null; // clear cached daemon client
+    // Close the daemon client before replacing with in-process client
+    if (typeof client.close === 'function') { try { await client.close(); } catch (_) {} }
+    _client = null;
     var mod = require(SERVER_BUNDLE);
     var configOrClass = mod.default || mod;
     var sdk = require('@frontmcp/sdk');
@@ -816,6 +892,7 @@ subscribeCmd
       process.on('SIGINT', async function() {
         console.log('\\nUnsubscribing...');
         try { await client.unsubscribeResource(uri); } catch (_) { /* ok */ }
+        await closeClient();
         process.exit(0);
       });
       // Keep process alive — setInterval creates an active event loop handle
@@ -842,8 +919,9 @@ subscribeCmd
           console.log(fmt.formatSubscriptionEvent({ type: 'notification', method: notification.method, params: notification.params, timestamp: new Date().toISOString() }, mode));
         }
       });
-      process.on('SIGINT', function() {
+      process.on('SIGINT', async function() {
         console.log('\\nStopping...');
+        await closeClient();
         process.exit(0);
       });
       // Keep process alive — setInterval creates an active event loop handle
@@ -984,6 +1062,7 @@ function generateServeCommand(serverBundleFilename, selfContained) {
   .description('Start the HTTP/SSE server')
   .option('-p, --port <port>', 'Port number', function(v) { return parseInt(v, 10); })
   .action(async function(opts) {
+    _isLongRunning = true;
     var mod = ${requireExpr};
     if (opts.port) process.env.PORT = String(opts.port);
     // If the bundle exports a start() function (@FrontMcp-decorated class auto-bootstraps), use it
@@ -1110,13 +1189,20 @@ function generateInstallCommand(appName, nativeDeps, selfContained) {
     console.log('Installing ${appName}...');
     dirs.forEach(function(d) { fs.mkdirSync(d, { recursive: true }); });
 
-    // Copy bundle files
+    // Copy bundle files and skill content
     var files = fs.readdirSync(SCRIPT_DIR).filter(function(f) {
-      return f.endsWith('.js') || f.endsWith('.json')${selfContained ? " || f.endsWith('-bin')" : ''};
+      return f.endsWith('.js') || f.endsWith('.json') || f.endsWith('.md')${selfContained ? " || f.endsWith('-bin')" : ''};
     });
     files.forEach(function(f) {
       fs.copyFileSync(pathMod.join(SCRIPT_DIR, f), pathMod.join(appDir, f));
     });
+    // Copy skill content directories (only those that exist in the build output)
+    var entries = fs.readdirSync(SCRIPT_DIR, { withFileTypes: true });
+    entries.forEach(function(ent) {
+      if (ent.isDirectory()) {
+        fs.cpSync(pathMod.join(SCRIPT_DIR, ent.name), pathMod.join(appDir, ent.name), { recursive: true });
+      }
+    });
     console.log('  Copied ' + files.length + ' files to ' + appDir);
 
     // Install native deps
@@ -1253,6 +1339,10 @@ ${selfContained ? `    // SEA mode: spawn the binary itself in daemon mode — a
       env: env
     });`}
 
+    // Close inherited file descriptors in the parent — the child already has its own copy.
+    fs.closeSync(out);
+    fs.closeSync(err);
+
     fs.writeFileSync(pidPath, JSON.stringify({
       pid: child.pid,
       socketPath: socketPath,
@@ -1335,8 +1425,16 @@ function generateFooter() {
   console.error('Unknown command: ' + args[0]);
   process.exitCode = 1;
 });
-program.parseAsync(process.argv).catch(function(err) {
+program.parseAsync(process.argv).then(async function() {
+  // Long-running commands (serve) set _isLongRunning to keep the event loop alive.
+  // Short-lived commands close the client and exit explicitly to avoid hanging
+  // on unclosed handles (file loggers, in-memory transport, etc.).
+  if (_isLongRunning) return;
+  await closeClient();
+  process.exit(process.exitCode || 0);
+}).catch(async function(err) {
   console.error('Fatal:', err.message || err);
+  await closeClient();
   process.exit(1);
 });`;
 }