mcp-google-multi 5.4.1-alpha.2 → 6.0.0-alpha.2

package/dist/config-file.js

@@ -0,0 +1,117 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { homedir } from 'node:os';
+import { z } from 'zod';
+import { atomicWriteFileSync, withFileLock } from './fs-atomic.js';
+export const CONFIG_VERSION = 1;
+export function configDir(env = process.env) {
+    return path.join(env.XDG_CONFIG_HOME || path.join(homedir(), '.config'), 'mcp-google-multi');
+}
+export function configFilePath(env = process.env) {
+    return path.join(configDir(env), 'config.json');
+}
+// Alias charset is load-bearing security, not cosmetics: the alias becomes a
+// tokenDir path segment (encPath), so this guard blocks path traversal.
+export const ALIAS_RE = /^[a-zA-Z0-9_-]+$/;
+const accountEntrySchema = z.strictObject({
+    email: z.string().min(1),
+    scopeProfile: z.string().optional(),
+    admin: z.boolean().optional(),
+});
+// .strict() everywhere: any unknown or secret-shaped key (clientSecret,
+// masterKey, jwtKey, clientId) fails validation, structurally enforcing
+// secrets-env-only. scopeProfiles/defaultAccount/discovery/toolsets are part
+// of the frozen envelope; their consumers land in later slices.
+const RESERVED_ALIASES = ['__proto__', 'constructor', 'prototype'];
+const configSchema = z.strictObject({
+    version: z.number().int(),
+    accounts: z.record(z.string().regex(ALIAS_RE), accountEntrySchema).optional(),
+    scopeProfiles: z
+        .record(z.string().regex(ALIAS_RE), z.strictObject({
+        bundles: z.array(z.string()),
+        admin: z.boolean().optional(),
+        includesBase: z.boolean().optional(),
+    }))
+        .optional(),
+    defaultAccount: z.string().optional(),
+    discovery: z.enum(['lazy', 'curated', 'eager']).optional(),
+    toolsets: z.string().optional(),
+});
+export function failStartup(slug, message) {
+    process.stderr.write(`${slug}: ${message}\n`);
+    process.exit(1);
+}
+export class ConfigFileError extends Error {
+    slug;
+    constructor(slug, message) {
+        super(`${slug}: ${message}`);
+        this.slug = slug;
+    }
+}
+/**
+ * Load + validate config.json. Returns null when the file does not exist.
+ * onInvalid 'exit' is for boot/CLI only; runtime reload paths use 'throw' so a
+ * mid-edit or corrupt file can NEVER kill a running server (and so lock
+ * finally-cleanup still runs).
+ */
+export function loadConfigFile(filePath = configFilePath(), onInvalid = 'exit') {
+    let raw;
+    try {
+        raw = fs.readFileSync(filePath, 'utf8');
+    }
+    catch (e) {
+        if (e.code === 'ENOENT')
+            return null;
+        throw e;
+    }
+    function fail(slug, message) {
+        if (onInvalid === 'throw')
+            throw new ConfigFileError(slug, message);
+        failStartup(slug, message);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        fail('E_CONFIG_INVALID', `${filePath} is not valid JSON.`);
+    }
+    const version = parsed?.version;
+    if (typeof version === 'number' && version > CONFIG_VERSION) {
+        fail('E_CONFIG_VERSION_UNSUPPORTED', `${filePath} has version ${version}; this build understands up to ${CONFIG_VERSION}. Upgrade mcp-google-multi.`);
+    }
+    const result = configSchema.safeParse(parsed);
+    if (!result.success) {
+        const issue = result.error.issues[0];
+        fail('E_CONFIG_INVALID', `${filePath}: ${issue.path.join('.') || '(root)'}: ${issue.message}. Secrets never belong in config.json.`);
+    }
+    // Post-schema because zod's key regex passes these; a __proto__ record key
+    // is a prototype-pollution foothold, and Object.prototype member names break
+    // plain-object lookups downstream.
+    const data = result.data;
+    for (const [section, keys] of [
+        ['accounts', Object.keys(data.accounts ?? {})],
+        ['scopeProfiles', Object.keys(data.scopeProfiles ?? {})],
+    ]) {
+        const reserved = keys.find((k) => RESERVED_ALIASES.includes(k));
+        if (reserved) {
+            fail('E_CONFIG_INVALID', `${filePath}: ${section}: reserved name "${reserved}".`);
+        }
+    }
+    return data;
+}
+export function writeConfigFile(config, filePath = configFilePath()) {
+    atomicWriteFileSync(filePath, `${JSON.stringify(config, null, 2)}\n`, 0o600);
+}
+/**
+ * Read-latest-under-lock mutation: acquire the lock, re-read the current file,
+ * apply the change to that (never a stale in-memory copy), write atomically.
+ */
+export function mutateConfigFile(fn, filePath = configFilePath()) {
+    return withFileLock(filePath, () => {
+        const current = loadConfigFile(filePath, 'throw') ?? { version: CONFIG_VERSION };
+        const next = fn(structuredClone(current));
+        writeConfigFile(next, filePath);
+        return next;
+    }, 'E_CONFIG_LOCK_TIMEOUT (config.json)');
+}

package/dist/discover.js

@@ -5,14 +5,68 @@ function opVocabulary(registry, service) {
     return [...new Set(ops)].join(', ');
 }
 export function registerDiscoverTools(registry, policy) {
+    const registerMeta = registry.registerMeta;
+    // Agent-controllable runtime expansion (D3 refinement): reveal the whole
+    // curated quality layer for heavy Google work, collapse to reclaim the
+    // name/schema context budget after. stdio-only semantics — over stateless
+    // HTTP the mode is forced curated and these are no-ops.
+    registerMeta('discover_all', {
+        description: 'Reveal ALL curated Google tools at once (instead of per-service discovery). ' +
+            'Use when starting substantial Google work so the shaped, high-quality tools are ' +
+            'directly callable; prefer them over google_api_call. Pair with discover_reset when done.',
+        inputSchema: {},
+        _meta: { 'anthropic/alwaysLoad': true },
+    }, async () => {
+        const changed = registry.expand();
+        const counts = registry.visibleCount();
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: JSON.stringify({
+                        expanded: changed,
+                        visibleTools: counts.eager + counts.revealed,
+                        note: changed
+                            ? 'Curated tools are now advertised. Generated long-tail tools still appear per-service via {service}_discover.'
+                            : 'Surface was already expanded (or the configured mode already advertises curated tools).',
+                    }),
+                },
+            ],
+        };
+    });
+    registerMeta('discover_reset', {
+        description: 'Collapse the tool surface back to the configured default (lean meta-tools-only under the ' +
+            'default lazy mode), reclaiming context budget after heavy Google work. All tools remain ' +
+            'callable by name after collapsing.',
+        inputSchema: {},
+        _meta: { 'anthropic/alwaysLoad': true },
+    }, async () => {
+        const changed = registry.collapse();
+        const counts = registry.visibleCount();
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: JSON.stringify({
+                        collapsed: changed,
+                        visibleTools: counts.eager + counts.revealed,
+                        note: 'Hidden tools stay callable by name (graceful dispatch); re-expand any time with discover_all.',
+                    }),
+                },
+            ],
+        };
+    });
     for (const service of registry.services()) {
-        registry.registerMeta(`${service}_discover`, {
-            description: `List the available ${service} operations. Operational ${service} tools are hidden ` +
-                `until discovered — call this first, then call the tool you need by name. ` +
+        registerMeta(`${service}_discover`, {
+            description: `List the available ${service} operations. ` +
+                (registry.mode === 'lazy'
+                    ? `Operational ${service} tools are hidden until discovered — call this first, then call the tool you need by name. `
+                    : `Returns the ${service} catalog (and reveals any still-hidden ${service} tools). `) +
                 `Operations: ${opVocabulary(registry, service)}.`,
             inputSchema: {
                 query: z.string().optional().describe('Keyword to filter the returned operations'),
             },
+            _meta: { 'anthropic/alwaysLoad': true },
         }, async ({ query }) => {
             const operations = registry.catalog(service, query);
             registry.reveal(service);

package/dist/doctor.d.ts

@@ -0,0 +1,86 @@
+import type { ToolRegistry } from './registry.js';
+import { getAccountSet } from './accounts.js';
+import { type AccountHealth } from './tools/accounts-tool.js';
+import { peekMasterKeyProvenance } from './master-key.js';
+export type Verdict = 'ok' | 'warn' | 'fail' | 'unknown';
+export interface DiagnosticSection {
+    id: number;
+    title: string;
+    verdict: Verdict;
+    lines: string[];
+    /** copy-pasteable remediation (gh-CLI style), attached only on warn/fail. */
+    hint?: string;
+    slug?: string;
+}
+export interface DiagnosticsReport {
+    verdict: Verdict;
+    sections: DiagnosticSection[];
+}
+/** One API-enablement probe outcome for a single service (section 6). */
+export interface ApiProbeResult {
+    service: string;
+    /** discovery API id used for the per-API console deep-link, e.g. "gmail". */
+    api: string;
+    ok: boolean;
+    /** true only for accessNotConfigured / SERVICE_DISABLED (the actionable case). */
+    notEnabled?: boolean;
+    message?: string;
+}
+export interface DiagnosticsDeps {
+    nodeVersion: string;
+    env: Record<string, string | undefined>;
+    cwd: string;
+    accountSet: () => ReturnType<typeof getAccountSet> | null;
+    accountHealth: (alias: string) => AccountHealth;
+    masterKeyProvenance: () => ReturnType<typeof peekMasterKeyProvenance>;
+    anyTokensExist: (aliases: string[]) => boolean;
+    fileExists: (p: string) => boolean;
+    /** Optional live section-6 probe; when absent the section reports `unknown`
+     * (spec: a section that cannot run is unknown, not FAIL). */
+    probeApi?: (alias: string) => Promise<ApiProbeResult[]>;
+}
+/** Console deep-link to enable one API (section-6 hint, error taxonomy B10). */
+export declare function apiEnableLink(api: string): string;
+/** Roll section verdicts to an overall verdict. `unknown` never worsens it. */
+export declare function overallVerdict(sections: DiagnosticSection[]): Verdict;
+export declare function runDiagnostics(deps?: DiagnosticsDeps): Promise<DiagnosticsReport>;
+/** doctor CLI (brew-doctor style): glyph-coded human report. */
+export declare function renderDoctorText(report: DiagnosticsReport): string;
+/** Redacted, paste-ready bug report (BR8): verdicts + provenance labels + token
+ * statuses + slugs; NO token values, secrets, keys, or full email addresses. */
+export declare function renderReport(report: DiagnosticsReport, version: string): string;
+/** Exit non-zero when any section FAILs; with strict, WARN counts too. */
+export declare function exitCodeFor(report: DiagnosticsReport, strict: boolean): number;
+/** Agent-callable structured health report (read-only). Mirrors `doctor`'s
+ * engine; NOT alwaysLoad (the agent asks for it when diagnosing). */
+export declare function registerDiagnoseTool(registry: ToolRegistry): void;
+export interface ResetOptions {
+    account?: string;
+    regenerateKey: boolean;
+    yes: boolean;
+}
+export interface ResetPlan {
+    wipeAliases: string[];
+    regenerateKey: boolean;
+}
+export type ResetPlanResult = {
+    ok: true;
+    plan: ResetPlan;
+    reauth: string[];
+} | {
+    ok: false;
+    slug: string;
+    message: string;
+};
+/** Pure planner (unit-testable): decide which token files to wipe and whether
+ * key regeneration is safe. Refuses --regenerate-key while any account outside
+ * the wipe set still holds an encrypted token (a fresh key would brick it). */
+export declare function planReset(opts: ResetOptions, state: {
+    aliases: string[];
+    tokenPresent: (a: string) => boolean;
+}): ResetPlanResult;
+/** CLI entry for `mcp-google-multi reset` (flags: --account, --regenerate-key,
+ * --yes). Confirmation-gated; config.json is always kept. */
+export declare function runResetCli(argv: string[]): Promise<number>;
+/** CLI entry for `mcp-google-multi doctor` (flags: --json, --strict, --report). */
+export declare function runDoctorCli(argv: string[], version: string): Promise<number>;

package/dist/doctor.js

@@ -0,0 +1,384 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as readline from 'node:readline';
+import { getAccountSet } from './accounts.js';
+import { deriveAccountHealth } from './tools/accounts-tool.js';
+import { peekMasterKeyProvenance, deleteMasterKeyMaterial } from './master-key.js';
+import { hasToken } from './token-store.js';
+import { configDir } from './config-file.js';
+const MIN_NODE_MAJOR = 22;
+const DEFAULT_DEPS = {
+    nodeVersion: process.versions.node,
+    env: process.env,
+    cwd: process.cwd(),
+    accountSet: () => {
+        try {
+            return getAccountSet();
+        }
+        catch {
+            return null;
+        }
+    },
+    accountHealth: (alias) => deriveAccountHealth(alias),
+    masterKeyProvenance: () => peekMasterKeyProvenance(),
+    anyTokensExist: (aliases) => aliases.some((a) => hasToken(a)),
+    fileExists: fs.existsSync,
+};
+/** Console deep-link to enable one API (section-6 hint, error taxonomy B10). */
+export function apiEnableLink(api) {
+    return `https://console.cloud.google.com/apis/library/${api}.googleapis.com`;
+}
+function transportsFrom(env) {
+    return (env.MCP_TRANSPORT ?? 'stdio')
+        .split(',')
+        .map((s) => s.trim().toLowerCase())
+        .filter(Boolean);
+}
+const LEGACY_ENV_KEYS = ['GOOGLE_ACCOUNTS', 'GOOGLE_OPTIONAL_SCOPES', 'GOOGLE_ADMIN_ACCOUNTS'];
+function sectionRuntime(deps) {
+    const major = Number.parseInt(deps.nodeVersion.split('.')[0] ?? '0', 10);
+    if (!Number.isFinite(major) || major < MIN_NODE_MAJOR) {
+        return {
+            id: 1,
+            title: 'Runtime',
+            verdict: 'fail',
+            slug: 'E_NODE_TOO_OLD',
+            lines: [`Node.js ${deps.nodeVersion} (requires >= ${MIN_NODE_MAJOR})`],
+            hint: `Upgrade to Node ${MIN_NODE_MAJOR} LTS or newer.`,
+        };
+    }
+    return { id: 1, title: 'Runtime', verdict: 'ok', lines: [`Node.js ${deps.nodeVersion} (>= ${MIN_NODE_MAJOR})`] };
+}
+function sectionConfig(deps, set) {
+    const lines = [];
+    let verdict = 'ok';
+    let hint;
+    let slug;
+    if (!set || set.aliases.length === 0) {
+        return {
+            id: 2,
+            title: 'Config',
+            verdict: 'fail',
+            slug: 'E_NO_ACCOUNTS_CONFIGURED',
+            lines: ['No accounts configured.'],
+            hint: 'Add an account: run `npx mcp-google-multi migrate-config` or set GOOGLE_ACCOUNTS.',
+        };
+    }
+    const cfgPath = path.join(configDir(), 'config.json');
+    lines.push(deps.fileExists(cfgPath) ? `config.json present (${set.aliases.length} account(s))` : `config.json absent — accounts sourced from env (${set.aliases.length})`);
+    const legacyEnv = LEGACY_ENV_KEYS.filter((k) => deps.env[k]);
+    if (legacyEnv.length > 0) {
+        verdict = 'warn';
+        slug = 'E_LEGACY_ENV';
+        lines.push(`Legacy env in effect: ${legacyEnv.join(', ')}`);
+        hint = 'Fold legacy env into config.json: `npx mcp-google-multi migrate-config`.';
+    }
+    // Legacy .env in CWD / package root shadows the ~/.config location.
+    for (const dir of [deps.cwd]) {
+        const envFile = path.join(dir, '.env');
+        if (deps.fileExists(envFile)) {
+            if (verdict === 'ok')
+                verdict = 'warn';
+            lines.push(`Legacy .env found at ${envFile}`);
+            const target = path.join(configDir(), '.env');
+            hint = (hint ? `${hint} ` : '') + `Move it: \`mv ${envFile} ${target}\`.`;
+        }
+    }
+    return { id: 2, title: 'Config', verdict, lines, ...(hint ? { hint } : {}), ...(slug ? { slug } : {}) };
+}
+function sectionKeys(deps, aliases) {
+    const provenance = deps.masterKeyProvenance();
+    const tokensExist = deps.anyTokensExist(aliases);
+    if (provenance === 'unprovisioned' && tokensExist) {
+        return {
+            id: 3,
+            title: 'Keys',
+            verdict: 'fail',
+            slug: 'E_MASTER_KEY_MISSING_TOKENS_EXIST',
+            lines: ['MASTER_KEY is unprovisioned but encrypted tokens exist — they cannot be decrypted.'],
+            hint: 'Restore the original MASTER_KEY, or `npx mcp-google-multi reset` and re-auth.',
+        };
+    }
+    const line = provenance === 'unprovisioned'
+        ? 'MASTER_KEY: unprovisioned (generated on first use)'
+        : `MASTER_KEY provenance: ${provenance}`;
+    return { id: 3, title: 'Keys', verdict: 'ok', lines: [line] };
+}
+function sectionsTokensAndScopes(deps, aliases) {
+    const tokenLines = [];
+    const scopeLines = [];
+    let tokenVerdict = 'ok';
+    let scopeVerdict = 'ok';
+    let tokenHint;
+    let scopeHint;
+    let sawMissing = false;
+    for (const alias of aliases) {
+        const h = deps.accountHealth(alias);
+        const s = h.token.status;
+        tokenLines.push(`${alias} (${h.email}): ${s}${h.token.expiryDate ? ` — expires ${h.token.expiryDate}` : ''}`);
+        if (s === 'missing' || s === 'needs_reauth' || s === 'decrypt_error') {
+            tokenVerdict = 'fail';
+            if (s === 'missing')
+                sawMissing = true;
+            if (h.token.hint)
+                tokenHint = h.token.hint;
+        }
+        else if (s === 'expired_refreshable' && tokenVerdict === 'ok') {
+            // refreshes transparently on next use — not a failure.
+            tokenLines[tokenLines.length - 1] += ' (auto-refreshes on use)';
+        }
+        const r = h.scopes;
+        if (r.requestable.length > 0) {
+            if (scopeVerdict === 'ok')
+                scopeVerdict = 'warn';
+            scopeLines.push(`${alias}: ${r.callable.length} callable, ${r.requestable.length} requested-not-granted`);
+            scopeHint = `Re-auth to grant missing scopes: \`npx mcp-google-multi auth --account ${alias}\`.`;
+        }
+        else {
+            scopeLines.push(`${alias}: ${r.callable.length} callable, all profile scopes granted`);
+        }
+    }
+    return [
+        { id: 4, title: 'Tokens', verdict: tokenVerdict, lines: tokenLines, ...(tokenHint ? { hint: tokenHint } : {}), ...(tokenVerdict === 'fail' ? { slug: sawMissing ? 'E_AUTH_REQUIRED' : 'E_REAUTH_REQUIRED' } : {}) },
+        { id: 5, title: 'Scopes', verdict: scopeVerdict, lines: scopeLines, ...(scopeHint ? { hint: scopeHint } : {}), ...(scopeVerdict === 'warn' ? { slug: 'E_SCOPE_NOT_GRANTED' } : {}) },
+    ];
+}
+async function sectionApiEnablement(deps, aliases) {
+    if (!deps.probeApi) {
+        return { id: 6, title: 'API enablement', verdict: 'unknown', lines: ['Probe not run (no live account probe configured).'] };
+    }
+    // Probe on the first alias with a live token; can't probe without one.
+    const healthy = aliases.find((a) => {
+        const st = deps.accountHealth(a).token.status;
+        return st === 'ok' || st === 'expired_refreshable';
+    });
+    if (!healthy) {
+        return { id: 6, title: 'API enablement', verdict: 'unknown', lines: ['No authenticated account to probe with.'] };
+    }
+    let results;
+    try {
+        results = await deps.probeApi(healthy);
+    }
+    catch (e) {
+        // Network / transient: WARN with the target, never crash the report.
+        return { id: 6, title: 'API enablement', verdict: 'warn', lines: [`Probe could not complete: ${e?.message ?? e}`] };
+    }
+    const disabled = results.filter((r) => r.notEnabled);
+    const lines = results.map((r) => `${r.service}: ${r.ok ? 'enabled' : r.notEnabled ? 'NOT ENABLED' : `unknown (${r.message ?? 'error'})`}`);
+    if (disabled.length > 0) {
+        return {
+            id: 6,
+            title: 'API enablement',
+            verdict: 'fail',
+            slug: 'E_API_NOT_ENABLED',
+            lines,
+            hint: disabled.map((r) => `Enable ${r.service}: ${apiEnableLink(r.api)}`).join('\n'),
+        };
+    }
+    return { id: 6, title: 'API enablement', verdict: 'ok', lines: lines.length ? lines : ['(probed account, all enabled)'] };
+}
+function sectionHttpDeferred(deps) {
+    if (!transportsFrom(deps.env).includes('http'))
+        return null;
+    return {
+        id: 7,
+        title: 'HTTP',
+        verdict: 'unknown',
+        lines: ['HTTP diagnostics (MCP_PUBLIC_URL canonicalization, MCP_OWNER_EMAILS, PRM/AS-metadata self-fetch) land with the OAuth authorization server (not yet built).'],
+    };
+}
+const RANK = { ok: 0, unknown: 0, warn: 1, fail: 2 };
+/** Roll section verdicts to an overall verdict. `unknown` never worsens it. */
+export function overallVerdict(sections) {
+    let worst = 'ok';
+    for (const s of sections) {
+        if (RANK[s.verdict] > RANK[worst])
+            worst = s.verdict;
+    }
+    return worst;
+}
+export async function runDiagnostics(deps = DEFAULT_DEPS) {
+    const sections = [];
+    sections.push(sectionRuntime(deps));
+    const set = deps.accountSet();
+    sections.push(sectionConfig(deps, set));
+    const aliases = set?.aliases ?? [];
+    sections.push(sectionKeys(deps, aliases));
+    if (aliases.length > 0) {
+        const [tokens, scopes] = sectionsTokensAndScopes(deps, aliases);
+        sections.push(tokens, scopes);
+        sections.push(await sectionApiEnablement(deps, aliases));
+    }
+    const http = sectionHttpDeferred(deps);
+    if (http)
+        sections.push(http);
+    return { verdict: overallVerdict(sections), sections };
+}
+// --- skins -----------------------------------------------------------------
+const GLYPH = { ok: '✔', warn: '!', fail: '✖', unknown: '·' };
+/** doctor CLI (brew-doctor style): glyph-coded human report. */
+export function renderDoctorText(report) {
+    const out = [];
+    for (const s of report.sections) {
+        out.push(`${GLYPH[s.verdict]} ${s.id}. ${s.title} [${s.verdict.toUpperCase()}]`);
+        for (const l of s.lines)
+            out.push(`    ${l}`);
+        if (s.hint)
+            for (const hl of s.hint.split('\n'))
+                out.push(`    → ${hl}`);
+    }
+    out.push('');
+    out.push(`Overall: ${report.verdict.toUpperCase()}`);
+    return out.join('\n');
+}
+/** Mask the local-part of an email so a report never carries a full address (BR8). */
+function maskEmails(text) {
+    return text.replace(/([A-Za-z0-9._%+-])[A-Za-z0-9._%+-]*(@[A-Za-z0-9.-]+)/g, '$1***$2');
+}
+/** Redacted, paste-ready bug report (BR8): verdicts + provenance labels + token
+ * statuses + slugs; NO token values, secrets, keys, or full email addresses. */
+export function renderReport(report, version) {
+    const out = [`mcp-google-multi doctor report (v${version})`, `overall: ${report.verdict}`, ''];
+    for (const s of report.sections) {
+        out.push(`[${s.id}] ${s.title}: ${s.verdict}${s.slug ? ` (${s.slug})` : ''}`);
+        for (const l of s.lines)
+            out.push(`  ${maskEmails(l)}`);
+    }
+    return out.join('\n');
+}
+/** Exit non-zero when any section FAILs; with strict, WARN counts too. */
+export function exitCodeFor(report, strict) {
+    if (report.verdict === 'fail')
+        return 1;
+    if (strict && report.verdict === 'warn')
+        return 1;
+    return 0;
+}
+/** Agent-callable structured health report (read-only). Mirrors `doctor`'s
+ * engine; NOT alwaysLoad (the agent asks for it when diagnosing). */
+export function registerDiagnoseTool(registry) {
+    registry.registerTool('diagnose', {
+        annotations: { readOnlyHint: true, openWorldHint: true },
+        description: 'Health report for this server: runtime, config, keys, per-account token status, scope grants, and API enablement. Read-only; returns copy-pasteable fixes for anything wrong. Call this to diagnose auth/config failures.',
+        inputSchema: {},
+    }, async () => {
+        try {
+            const result = await runDiagnostics();
+            return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+        }
+        catch (e) {
+            return { content: [{ type: 'text', text: JSON.stringify({ error: 'diagnose_failed', message: e?.message ?? String(e) }) }], isError: true };
+        }
+    });
+}
+/** Pure planner (unit-testable): decide which token files to wipe and whether
+ * key regeneration is safe. Refuses --regenerate-key while any account outside
+ * the wipe set still holds an encrypted token (a fresh key would brick it). */
+export function planReset(opts, state) {
+    if (opts.account && !state.aliases.includes(opts.account)) {
+        return { ok: false, slug: 'E_VALIDATION', message: `Unknown account "${opts.account}". Known: ${state.aliases.join(', ') || '(none)'}.` };
+    }
+    const wipeAliases = opts.account ? [opts.account] : [...state.aliases];
+    if (opts.regenerateKey) {
+        const remaining = state.aliases.filter((a) => !wipeAliases.includes(a) && state.tokenPresent(a));
+        if (remaining.length > 0) {
+            return {
+                ok: false,
+                slug: 'E_KEY_REGEN_BLOCKED',
+                message: `Refusing --regenerate-key: ${remaining.length} account(s) still hold encrypted tokens (${remaining.join(', ')}). Wipe all accounts (omit --account) or drop --regenerate-key.`,
+            };
+        }
+    }
+    const reauth = wipeAliases.filter((a) => state.tokenPresent(a));
+    return { ok: true, plan: { wipeAliases, regenerateKey: opts.regenerateKey }, reauth };
+}
+function parseResetOptions(argv) {
+    const at = argv.indexOf('--account');
+    return {
+        account: at >= 0 ? argv[at + 1] : undefined,
+        regenerateKey: argv.includes('--regenerate-key'),
+        yes: argv.includes('--yes'),
+    };
+}
+async function confirmTty(prompt) {
+    const rl = readline.createInterface({ input: process.stdin, output: process.stderr });
+    try {
+        const answer = await new Promise((resolve) => rl.question(prompt, resolve));
+        return answer.trim().toLowerCase() === 'yes';
+    }
+    finally {
+        rl.close();
+    }
+}
+/** CLI entry for `mcp-google-multi reset` (flags: --account, --regenerate-key,
+ * --yes). Confirmation-gated; config.json is always kept. */
+export async function runResetCli(argv) {
+    const opts = parseResetOptions(argv);
+    const set = (() => { try {
+        return getAccountSet();
+    }
+    catch {
+        return null;
+    } })();
+    const aliases = set?.aliases ?? [];
+    const planned = planReset(opts, { aliases, tokenPresent: (a) => hasToken(a) });
+    if (!planned.ok) {
+        console.error(`${planned.slug}: ${planned.message}`);
+        return 1;
+    }
+    const { plan, reauth } = planned;
+    const summary = `About to wipe tokens for: ${plan.wipeAliases.join(', ') || '(no accounts)'}` +
+        (plan.regenerateKey ? ' AND regenerate the MASTER_KEY' : '') + '. config.json is kept.';
+    if (!opts.yes) {
+        if (!process.stdin.isTTY) {
+            console.error(`E_INPUT_REQUIRED: ${summary}\nRe-run with --yes to confirm (non-interactive).`);
+            return 1;
+        }
+        const ok = await confirmTty(`${summary}\nType 'yes' to confirm: `);
+        if (!ok) {
+            console.error('confirmation_declined: nothing was changed.');
+            return 1;
+        }
+    }
+    // Execute: delete each alias's encrypted token file (config.json untouched).
+    let wiped = 0;
+    for (const alias of plan.wipeAliases) {
+        const encPath = set?.configs[alias]?.encPath;
+        if (!encPath)
+            continue;
+        try {
+            fs.unlinkSync(encPath);
+            wiped++;
+        }
+        catch {
+            // already gone
+        }
+    }
+    console.log(`Wiped ${wiped} token file(s).`);
+    if (plan.regenerateKey) {
+        const res = deleteMasterKeyMaterial();
+        console.log(`MASTER_KEY material removed (file: ${res.file}, keychain: ${res.keychain}).`);
+        if (res.env)
+            console.log('Note: MASTER_KEY is still set in the environment; unset it to let a fresh key generate.');
+    }
+    if (reauth.length > 0) {
+        console.log('\nNext, re-authenticate each wiped account:');
+        for (const alias of reauth)
+            console.log(`  npx mcp-google-multi auth --account ${alias}`);
+    }
+    return 0;
+}
+/** CLI entry for `mcp-google-multi doctor` (flags: --json, --strict, --report). */
+export async function runDoctorCli(argv, version) {
+    const json = argv.includes('--json');
+    const strict = argv.includes('--strict');
+    const report = argv.includes('--report');
+    const result = await runDiagnostics();
+    if (json)
+        console.log(JSON.stringify(result, null, 2));
+    else if (report)
+        console.log(renderReport(result, version));
+    else
+        console.log(renderDoctorText(result));
+    return exitCodeFor(result, strict);
+}

package/dist/env-load.d.ts

@@ -0,0 +1,11 @@
+export interface EnvLoadResult {
+    loaded: string[];
+    searched: string[];
+}
+/** Path overrides are for tests only; production callers pass nothing. */
+export interface EnvLoadPaths {
+    cwd?: string;
+    packageRoot?: string;
+    configDir?: string;
+}
+export declare function loadEnvFiles(paths?: EnvLoadPaths): EnvLoadResult;