fluxmail 0.9.0 → 0.11.0

package/dist/cli.js

@@ -25,13 +25,14 @@ import { VERSION } from './version.js';
 import { inspectStoreCompatibility, MIN_SUPPORTED_STORE_FORMAT, openDb, openReadonlyDb, } from './storage/db.js';
 import { customPermissionPolicy, ADMIN_CAPABILITIES, FULL_PERMISSION_POLICY, isNamedPermissionProfile, MCP_CAPABILITIES, NAMED_PERMISSION_PROFILES, permissionPolicyForProfile, } from './permissions.js';
 import { captureOperation, getTelemetry, installTelemetryStreamEndHandler, isTelemetryEnabled, setTelemetryEnabled, shutdownTelemetry, telemetryDisabledInAnyEnvironment, } from './telemetry.js';
-import { apiErrorCode, clearSessionToken, instanceClient, loadInstanceConfig, removeInstance, resolveInstance, saveLocalInstance, saveRemoteInstance, saveSessionToken, useInstance, } from './cliInstances.js';
+import { apiErrorCode, apiRequestId, clearSessionToken, instanceClient, loadInstanceConfig, removeInstance, resolveInstance, saveLocalInstance, saveRemoteInstance, saveSessionToken, setRequestDeadlineMs, useInstance, } from './cliInstances.js';
+import { cliExitCode, parseOutputFormat, printOutput } from './cliOutput.js';
 import { authenticateBearer, isBootstrapComplete, normalizeAndValidatePassword, recoverAdminPassword, setupInitialAdmin, } from './auth.js';
 import { recordAdminAuditEvent } from './storage/adminAudit.js';
 import { canManageOwnedAccount } from './authorization.js';
 import { createCliUpdateNotifier } from './updateNotifier.js';
 import { registerMailCommands } from './cliMail.js';
-import { accountInventoryProperties, configuredOAuthAppKind, connectionProperties } from './accounts/telemetry.js';
+import { accountInventoryProperties, configuredOAuthAppKind, connectionProperties, instanceUsageProperties, } from './accounts/telemetry.js';
 import { flushLogging, escapeLogTextForConsole, getLogger, logCodedFailure, logFailure, readLocalLogs, shutdownLogging, } from './logging.js';
 function collectOption(value, previous) {
     return [...previous, value];
@@ -178,6 +179,33 @@ function readSecretFile(file) {
 async function secretInput(file, label) {
     return file === undefined ? hiddenPrompt(label) : readSecretFile(file);
 }
+/** Print the consent URL and explain how to finish when the redirect cannot reach this computer. */
+function printLoopbackInstructions(provider, url, context, port) {
+    const providerName = provider === 'gmail' ? 'Google' : 'Microsoft';
+    const access = provider === 'gmail' ? 'Gmail access' : 'Microsoft mail access';
+    console.log(`\nOpen this URL in your browser to authorize ${access}:\n`);
+    console.log(`  ${url}\n`);
+    if (!context.listening) {
+        console.log(`Port ${port} is already in use, so Fluxmail cannot receive the redirect from ${providerName}.\n\n` +
+            'If Fluxmail is running with Docker Compose, press Ctrl-C and connect the account inside the container ' +
+            'so it is saved there:\n\n' +
+            `  docker compose exec fluxmail fluxmail accounts add ${provider}\n\n` +
+            "Otherwise, approve access, then copy the full URL from your browser's address bar and paste it here.");
+        return;
+    }
+    console.log(`Waiting for ${providerName} to redirect back...`);
+    if (context.pasteEnabled) {
+        console.log('If your browser runs on another computer, the page will not load after you approve access. ' +
+            'Copy the full URL from its address bar and paste it here.');
+    }
+}
+/** Accept a pasted callback URL when a person is at the terminal, and report how the callback arrived. */
+function loopbackFlowOptions(program, provider) {
+    return {
+        ...(process.stdin.isTTY ? { paste: { input: process.stdin, write: (message) => console.error(message) } } : {}),
+        onCallback: (callback) => recordCliOperationProperties(program, connectionProperties({ provider, callback })),
+    };
+}
 /** Offered when a configured public URL, not an explicit --hosted, chose the hosted flow. */
 const LOOPBACK_FLOW_REMEDY = 'Pass --local to use the loopback flow on this computer instead.';
 function planLine(ent) {
@@ -248,9 +276,22 @@ function finishCliOperation(program, outcome, errorCode, error) {
 }
 /** End a failed command with the error's own telemetry code instead of a generic one. */
 function failCliOperation(program, error, prefix = 'Error: ') {
-    finishCliOperation(program, 'error', apiErrorCode(error), error);
-    console.error(`${prefix}${error instanceof Error ? error.message : String(error)}`);
-    process.exitCode = 1;
+    const code = apiErrorCode(error);
+    finishCliOperation(program, 'error', code, error);
+    let format = 'json';
+    try {
+        format = parseOutputFormat(program.opts().format ?? 'json');
+    }
+    catch {
+        // Report an invalid --format value in the default structured format.
+    }
+    const message = error instanceof Error ? error.message : String(error);
+    console.error(format === 'table'
+        ? `${prefix}${message}`
+        : JSON.stringify({
+            error: { code, message, ...(apiRequestId(error) ? { requestId: apiRequestId(error) } : {}) },
+        }));
+    process.exitCode = cliExitCode(code);
 }
 export function waitForServerListening(server) {
     return new Promise((resolve, reject) => {
@@ -295,10 +336,14 @@ export function createCliProgram(options = {}) {
         .description('Fluxmail, a self-hosted email API with MCP, REST, and CLI access')
         .option('--instance <name>', 'Use a named local or remote instance')
         .option('-a, --mail-account <id-or-email>', 'Use an email account by ID or address')
+        .option('--format <format>', 'Output format: json, table, or ndjson', 'json')
+        .option('--timeout <seconds>', 'Request deadline in seconds (1 to 300)', '30')
         .option('--no-update-notifier', 'Skip the automatic update check for this command')
         .version(VERSION, '-v, --version');
     const selectedInstance = () => program.opts().instance;
     const selectedAccount = () => program.opts().mailAccount;
+    const selectedFormat = () => parseOutputFormat(program.opts().format);
+    const capturedOutput = new Map();
     function commandPath(command) {
         const names = [];
         for (let current = command; current?.parent; current = current.parent)
@@ -337,6 +382,8 @@ export function createCliProgram(options = {}) {
         process.once('SIGHUP', onSighup);
     }
     program.hook('preAction', (_command, actionCommand) => {
+        selectedFormat();
+        setRequestDeadlineMs(Number(program.opts().timeout) * 1000);
         const command = commandPath(actionCommand);
         const updateNotifierEnabled = program.opts().updateNotifier;
         if (updateNotifierEnabled && actionCommand.name() !== 'stdio') {
@@ -390,8 +437,44 @@ export function createCliProgram(options = {}) {
             initialExitCode: process.exitCode,
             logger: getLogger(dataDir, mode, logging),
         });
+        const [group, action] = command.split(' ');
+        const alreadyStructured = ['folders', 'labels', 'emails', 'threads', 'drafts', 'scheduled', 'attachments'].includes(group ?? '') ||
+            command === 'accounts list' ||
+            command === 'status';
+        const interactive = ['setup', 'login', 'serve', 'stdio'].includes(command) ||
+            group === 'auth' ||
+            command === 'accounts add' ||
+            command === 'accounts configure' ||
+            command === 'license activate' ||
+            (group === 'oauth' && action !== 'status') ||
+            group === 'logs';
+        if (selectedFormat() !== 'table' && !alreadyStructured && !interactive) {
+            const original = console.log;
+            const lines = [];
+            capturedOutput.set(program, { original, lines });
+            console.log = (...values) => {
+                lines.push(values.map((value) => (typeof value === 'string' ? value : JSON.stringify(value))).join(' '));
+            };
+        }
     });
     program.hook('postAction', async (_command, actionCommand) => {
+        const captured = capturedOutput.get(program);
+        if (captured) {
+            capturedOutput.delete(program);
+            console.log = captured.original;
+            if (captured.lines.length) {
+                let data = captured.lines.length === 1 ? captured.lines[0] : captured.lines;
+                if (captured.lines.length === 1) {
+                    try {
+                        data = JSON.parse(captured.lines[0]);
+                    }
+                    catch {
+                        /* Plain output stays a string. */
+                    }
+                }
+                printOutput({ data }, selectedFormat());
+            }
+        }
         const active = activeCliOperations.get(program);
         const failed = active !== undefined &&
             process.exitCode !== active.initialExitCode &&
@@ -638,7 +721,11 @@ export function createCliProgram(options = {}) {
                 details: { port: ctx.config.port },
                 skipConsole: true,
             });
-            ctx.telemetry.capture('mcp server started', { product_surface: 'mcp', transport: 'http' });
+            ctx.telemetry.capture('mcp server started', {
+                ...instanceUsageProperties(ctx.db),
+                product_surface: 'mcp',
+                transport: 'http',
+            });
             console.log(`Fluxmail listening on ${ctx.config.publicUrl}`);
             console.log(`  MCP endpoint:   ${ctx.config.publicUrl}/mcp`);
             console.log(`  REST API:       ${ctx.config.publicUrl}/api/v1`);
@@ -692,7 +779,11 @@ export function createCliProgram(options = {}) {
         });
         ctx.scheduler.start();
         await server.connect(new StdioServerTransport());
-        ctx.telemetry.capture('mcp server started', { product_surface: 'mcp', transport: 'stdio' });
+        ctx.telemetry.capture('mcp server started', {
+            ...instanceUsageProperties(ctx.db),
+            product_surface: 'mcp',
+            transport: 'stdio',
+        });
         ctx.logger.info('server.started', 'Fluxmail stdio MCP server started', {
             productSurface: 'mcp',
             details: { transport: 'stdio' },
@@ -979,11 +1070,7 @@ export function createCliProgram(options = {}) {
                     console.log('This link expires in 10 minutes and can only be used once.');
                     return;
                 }
-                const account = await runMicrosoftLoopbackFlow(ctx.config, (url) => {
-                    console.log('\nOpen this URL in your browser to authorize Microsoft mail access:\n');
-                    console.log(`  ${url}\n`);
-                    console.log('Waiting for Microsoft to redirect back...');
-                }, (result) => {
+                const account = await runMicrosoftLoopbackFlow(ctx.config, (url, context) => printLoopbackInstructions('outlook', url, context, ctx.config.oauthPort), (result) => {
                     const duplicate = ctx.registry
                         .listAccounts()
                         .find((candidate) => candidate.email.toLowerCase() === result.email.toLowerCase());
@@ -995,7 +1082,7 @@ export function createCliProgram(options = {}) {
                             'Try again and choose the matching Microsoft account.');
                     }
                     return ctx.registry.addOutlookAccount(result.email, result.credentials, result.displayName, owner.id, existing?.id, access);
-                });
+                }, loopbackFlowOptions(program, 'outlook'));
                 auditConnection('account.connection.complete', account.id);
                 recordCliOperationProperties(program, {
                     reauthorize: accountIdsBeforeConnection.has(account.id),
@@ -1018,11 +1105,7 @@ export function createCliProgram(options = {}) {
                 console.log('This link expires in 10 minutes and can only be used once.');
                 return;
             }
-            const account = await runLoopbackFlow(ctx.config, (url) => {
-                console.log('\nOpen this URL in your browser to authorize Gmail access:\n');
-                console.log(`  ${url}\n`);
-                console.log('Waiting for Google to redirect back…');
-            }, (result) => {
+            const account = await runLoopbackFlow(ctx.config, (url, context) => printLoopbackInstructions('gmail', url, context, ctx.config.oauthPort), (result) => {
                 const duplicate = ctx.registry
                     .listAccounts()
                     .find((candidate) => candidate.email.toLowerCase() === result.email.toLowerCase());
@@ -1034,7 +1117,7 @@ export function createCliProgram(options = {}) {
                         'Try again and choose the matching Google account.');
                 }
                 return ctx.registry.addGmailAccount(result.email, result.tokens, result.displayName, owner.id, access, result.oauthClient);
-            });
+            }, loopbackFlowOptions(program, 'gmail'));
             auditConnection('account.connection.complete', account.id);
             recordCliOperationProperties(program, {
                 reauthorize: accountIdsBeforeConnection.has(account.id),
@@ -1097,18 +1180,7 @@ export function createCliProgram(options = {}) {
         .action(async () => {
         try {
             const all = await instanceClient(selectedInstance()).json('/api/v1/accounts');
-            if (!all.length) {
-                console.log('No accounts connected. Run "fluxmail accounts add <provider>".');
-                return;
-            }
-            for (const a of all) {
-                const access = a.sharedWithAll
-                    ? 'all'
-                    : a.grantedMemberIds.length
-                        ? `selected:${a.grantedMemberIds.join(',')}`
-                        : 'owner-only';
-                console.log(`${a.id}  ${a.provider}  ${a.email}  [${a.status}]  owner=${a.ownerMemberId}  access=${access}`);
-            }
+            printOutput({ data: all }, selectedFormat());
         }
         catch (err) {
             failCliOperation(program, err);
@@ -1188,7 +1260,7 @@ export function createCliProgram(options = {}) {
         .requiredOption('--name <name>', 'Member name')
         .requiredOption('--email <email>', 'Member login email')
         .option('--role <role>', 'Member role: admin or member')
-        .description('Add a member (subject to the plan seat limit)')
+        .description("Add a member (subject to your plan's member limit)")
         .action(async (opts) => {
         try {
             if (opts.role && opts.role !== 'admin' && opts.role !== 'member') {
@@ -1752,14 +1824,20 @@ export function createCliProgram(options = {}) {
     registerMailCommands(program, {
         selectedInstance,
         selectedAccount,
+        selectedFormat,
         reportError: (error, code) => {
             finishCliOperation(program, 'error', code, error);
-            console.error(`Error [${code}]: ${error instanceof Error ? error.message : String(error)}`);
-            process.exitCode = 1;
+            const message = error instanceof Error ? error.message : String(error);
+            console.error(selectedFormat() === 'table'
+                ? `Error [${code}]: ${message}`
+                : JSON.stringify({
+                    error: { code, message, ...(apiRequestId(error) ? { requestId: apiRequestId(error) } : {}) },
+                }));
+            process.exitCode = cliExitCode(code);
         },
         reportPartialFailure: (code) => {
             finishCliOperation(program, 'error', code);
-            process.exitCode = 1;
+            process.exitCode = cliExitCode(code);
         },
     });
     program
@@ -1768,7 +1846,7 @@ export function createCliProgram(options = {}) {
         .action(async () => {
         try {
             const status = await instanceClient(selectedInstance()).json('/api/v1/status');
-            console.log(JSON.stringify(status, null, 2));
+            printOutput({ data: status }, selectedFormat());
         }
         catch (err) {
             failCliOperation(program, err);