ticketlens 0.38.19 → 0.38.21

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ticketlens",
-  "version": "0.38.19",
+  "version": "0.38.21",
   "description": "Jira CLI for developers — fetch ticket context, triage your queue, and stop tab-switching. Zero dependencies, all local.",
   "type": "module",
   "bin": {

package/skills/jtb/scripts/lib/doctor-checks.mjs

@@ -12,6 +12,8 @@
  * before any public (CLI plain/JSON or MCP) output.
  */
 
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
 import { DEFAULT_CONFIG_DIR } from './config.mjs';
 import { resolveProfile, loadCredentials, loadProfiles } from './profile-resolver.mjs';
 import { checkLicense, GRACE_DAYS } from './license.mjs';
@@ -21,6 +23,8 @@ import { testConnections } from './connection-tester.mjs';
 import { formatSize } from './attachment-downloader.mjs';
 import { getCacheEntries, filterEntriesByProfile } from './cache-manager.mjs';
 import { readQueue } from './recall-queue.mjs';
+import { readMcpConfig, ENTRY_NAME, DESIRED_MCP_ENTRY } from './mcp-install.mjs';
+import { testMcpHandshake, DEFAULT_HANDSHAKE_TIMEOUT_MS } from './mcp-handshake-checker.mjs';
 
 const NOOP_STREAM = { write: () => true };
 
@@ -155,7 +159,7 @@ export async function checkConnectivity({
   }
   const summary = results
     .map(r => r.ok ? `${r.name}: ok` : `${r.name}: ${r.error}${r.hint ? ` → ${r.hint}` : ''}`)
-    .join('; ');
+    .join('\n');
   return {
     id: 'connectivity', label: 'Tracker connectivity',
     ok: failedCount === 0,
@@ -217,3 +221,83 @@ export function checkRecallQueue({
     fixable: true,
   };
 }
+
+export function checkMcpRegistration({
+  cwd = process.cwd(),
+  existsSyncFn = existsSync,
+  readMcpConfigFn = readMcpConfig,
+} = {}) {
+  const configPath = join(cwd, '.mcp.json');
+  const read = readMcpConfigFn(configPath);
+
+  if (!read.ok) {
+    return {
+      id: 'mcp-registration', label: 'MCP registration', ok: false,
+      message: read.reason, hint: null, fixable: false,
+    };
+  }
+
+  const existing = read.config.mcpServers?.[ENTRY_NAME];
+  const registered = existing !== undefined && JSON.stringify(existing) === JSON.stringify(DESIRED_MCP_ENTRY);
+
+  if (registered) {
+    return {
+      id: 'mcp-registration', label: 'MCP registration', ok: true,
+      message: '"ticketlens" is registered in .mcp.json with the correct command and args.',
+      hint: null, fixable: false,
+    };
+  }
+
+  if (!existsSyncFn(configPath)) {
+    return {
+      id: 'mcp-registration', label: 'MCP registration', ok: false,
+      message: 'No .mcp.json file found in the current directory.',
+      hint: 'Run `ticketlens mcp install` to create it and register "ticketlens".',
+      fixable: true,
+    };
+  }
+
+  return {
+    id: 'mcp-registration', label: 'MCP registration', ok: false,
+    message: '"ticketlens" is not registered in .mcp.json.',
+    hint: 'Run `ticketlens mcp install` to register it.',
+    fixable: true,
+  };
+}
+
+// 'timeout' is handled separately below (its message embeds the actual
+// timeoutMs), so it has no entry here.
+const MCP_HANDSHAKE_MESSAGES = {
+  'spawn-error': 'Could not start "ticketlens mcp" — command not found or failed to launch.',
+  'invalid-response': '"ticketlens mcp" responded, but not with a valid initialize result.',
+};
+
+const MCP_HANDSHAKE_HINTS = {
+  'spawn-error': 'Confirm `ticketlens` is installed and on PATH, then run `ticketlens doctor --mcp` again.',
+  'timeout': 'Run `ticketlens doctor --mcp` again — if it keeps timing out, check for a hung `ticketlens mcp` process.',
+  'invalid-response': 'Run `ticketlens --version` to check the installed build; reinstall if the response looks corrupted.',
+};
+
+export async function checkMcpHandshake({
+  timeoutMs = DEFAULT_HANDSHAKE_TIMEOUT_MS,
+  testMcpHandshakeFn = testMcpHandshake,
+} = {}) {
+  const result = await testMcpHandshakeFn({ timeoutMs });
+
+  if (result.ok) {
+    return {
+      id: 'mcp-handshake', label: 'MCP server handshake', ok: true,
+      message: `MCP server handshake succeeded, protocol version ${result.protocolVersion}.`,
+      hint: null, fixable: false,
+    };
+  }
+
+  const message = result.reason === 'timeout'
+    ? `No response from "ticketlens mcp" within ${timeoutMs}ms.`
+    : MCP_HANDSHAKE_MESSAGES[result.reason] ?? 'MCP server handshake failed.';
+
+  return {
+    id: 'mcp-handshake', label: 'MCP server handshake', ok: false,
+    message, hint: MCP_HANDSHAKE_HINTS[result.reason] ?? null, fixable: false,
+  };
+}

package/skills/jtb/scripts/lib/doctor-command.mjs

@@ -10,15 +10,20 @@ import { handleUnknownFlags } from './arg-validator.mjs';
 import { createStyler } from './ansi.mjs';
 import {
   checkProfileConfig, checkLicenseFreshness, checkConnectivity,
-  checkCacheHealth, checkRecallQueue,
+  checkCacheHealth, checkRecallQueue, checkMcpRegistration, checkMcpHandshake,
 } from './doctor-checks.mjs';
 import { revalidateLicense } from './license.mjs';
 import { flushQueue } from './recall-queue.mjs';
 import { readCliToken } from './cli-auth.mjs';
+import { mcpInstall } from './mcp-install.mjs';
 
-const KNOWN_FLAGS = ['--format=', '--fix', '--profile=', '--help', '-h'];
+const KNOWN_FLAGS = ['--format=', '--fix', '--profile=', '--mcp', '--help', '-h'];
+const NOOP_STREAM = { write: () => true };
 
-const lowerFirst = (str) => str.charAt(0).toLowerCase() + str.slice(1);
+// A leading run of 2+ capitals is an acronym (e.g. "MCP registration") and
+// must not be partially lowercased — only a genuine single leading capital
+// (e.g. "Profile configuration") gets folded to start a sentence mid-line.
+const lowerFirst = (str) => (/^[A-Z]{2,}/.test(str) ? str : str.charAt(0).toLowerCase() + str.slice(1));
 
 function renderPlain(checks, { fixed, skipped, stream }) {
   const s = createStyler({ isTTY: stream.isTTY });
@@ -26,7 +31,9 @@ function renderPlain(checks, { fixed, skipped, stream }) {
   for (const check of checks) {
     const icon = check.ok ? s.green('✔') : s.red('✖');
     stream.write(`  ${icon} ${check.label}: ${check.message}\n`);
-    if (!check.ok && check.hint) stream.write(`      ${s.dim(check.hint)}\n`);
+    if (!check.ok && check.hint) {
+      for (const line of check.hint.split('\n')) stream.write(`      ${s.dim(line)}\n`);
+    }
   }
   if (fixed.length > 0) {
     stream.write(`\n  ${s.green('Fixed:')} ${fixed.join(', ')}\n`);
@@ -39,10 +46,11 @@ function renderPlain(checks, { fixed, skipped, stream }) {
 }
 
 async function applyFixes(rawResults, {
-  configDir, profileName, format, stream,
+  configDir, profileName, cwd, format, stream,
   revalidateLicenseFn, checkLicenseFreshnessFn,
   unlinkFn, checkCacheHealthFn,
   flushQueueFn, checkRecallQueueFn, readCliTokenFn,
+  mcpInstallFn, checkMcpRegistrationFn,
 }) {
   const fixed = [];
   const skipped = [];
@@ -79,6 +87,14 @@ async function applyFixes(rawResults, {
     }
   }
 
+  if (byId['mcp-registration'] && !byId['mcp-registration'].ok && byId['mcp-registration'].fixable) {
+    if (format === 'plain') stream.write('Registering ticketlens as an MCP server...\n');
+    mcpInstallFn({ cwd, stream: NOOP_STREAM, dryRun: false });
+    const recheck = checkMcpRegistrationFn({ cwd });
+    byId['mcp-registration'] = recheck;
+    if (recheck.ok) fixed.push('mcp-registration');
+  }
+
   return { results: Object.values(byId), fixed, skipped };
 }
 
@@ -92,10 +108,13 @@ export async function runDoctor(args, {
   checkConnectivityFn = checkConnectivity,
   checkCacheHealthFn = checkCacheHealth,
   checkRecallQueueFn = checkRecallQueue,
+  checkMcpRegistrationFn = checkMcpRegistration,
+  checkMcpHandshakeFn = checkMcpHandshake,
   revalidateLicenseFn = revalidateLicense,
   unlinkFn = (p) => fs.unlinkSync(p),
   flushQueueFn = flushQueue,
   readCliTokenFn = readCliToken,
+  mcpInstallFn = mcpInstall,
 } = {}) {
   const validated = await handleUnknownFlags(args, KNOWN_FLAGS, { stream });
   if (validated === null) return { ok: false };
@@ -110,6 +129,7 @@ export async function runDoctor(args, {
   const profileArg = validated.find(a => a.startsWith('--profile='));
   const profileName = profileArg ? profileArg.split('=')[1] : null;
   const shouldFix = validated.includes('--fix');
+  const shouldCheckMcpHandshake = validated.includes('--mcp');
 
   const checkList = [
     { label: 'Profile configuration', run: () => checkProfileConfigFn({ configDir, profileName, cwd }) },
@@ -117,6 +137,8 @@ export async function runDoctor(args, {
     { label: 'Tracker connectivity', run: () => checkConnectivityFn({ configDir, profileName, cwd }) },
     { label: 'Attachment cache', run: () => checkCacheHealthFn({ configDir, profileName }) },
     { label: 'Recall sync queue', run: () => checkRecallQueueFn({ configDir }) },
+    { label: 'MCP registration', run: () => checkMcpRegistrationFn({ cwd }) },
+    ...(shouldCheckMcpHandshake ? [{ label: 'MCP server handshake', run: () => checkMcpHandshakeFn({}) }] : []),
   ];
 
   const showProgress = format === 'plain' && stream.isTTY;
@@ -136,10 +158,11 @@ export async function runDoctor(args, {
   let finalResults = rawResults;
   if (shouldFix) {
     const applied = await applyFixes(rawResults, {
-      configDir, profileName, format, stream,
+      configDir, profileName, cwd, format, stream,
       revalidateLicenseFn, checkLicenseFreshnessFn,
       unlinkFn, checkCacheHealthFn,
       flushQueueFn, checkRecallQueueFn, readCliTokenFn,
+      mcpInstallFn, checkMcpRegistrationFn,
     });
     finalResults = applied.results;
     fixed = applied.fixed;

package/skills/jtb/scripts/lib/help.mjs

@@ -1230,11 +1230,12 @@ export function printDoctorHelp({ stream = process.stdout } = {}) {
   const s = createStyler({ isTTY: stream.isTTY });
   const lines = [
     '',
-    `  ${s.bold(s.brand('ticketlens'))} ${s.bold('doctor')} ${s.dim('[--fix] [--format=plain|json] [--profile=NAME]')}`,
+    `  ${s.bold(s.brand('ticketlens'))} ${s.bold('doctor')} ${s.dim('[--fix] [--format=plain|json] [--profile=NAME] [--mcp]')}`,
     '',
     `  Diagnose common TicketLens problems: profile configuration, license`,
-    `  freshness, tracker connectivity, attachment cache health, and the Recall`,
-    `  sync queue. Free tier, fully unrestricted.`,
+    `  freshness, tracker connectivity, attachment cache health, MCP`,
+    `  registration, and the Recall sync queue. Pass --mcp to also check the`,
+    `  MCP server handshake. Free tier, fully unrestricted.`,
     '',
     `  ${s.bold('OPTIONS')}`,
     '',
@@ -1242,6 +1243,7 @@ export function printDoctorHelp({ stream = process.stdout } = {}) {
     `    ${s.brand('--format')}=${s.dim('plain')}    Human-readable output  ${s.dim('(default)')}`,
     `    ${s.brand('--format')}=${s.dim('json')}     JSON output for scripting/piping`,
     `    ${s.brand('--profile')}=${s.dim('NAME')}    Scope profile/connectivity/cache checks to one profile`,
+    `    ${s.brand('--mcp')}              Also run the MCP server handshake check (spawns a subprocess)`,
     `    ${s.brand('-h')}, ${s.brand('--help')}         Show this help`,
     '',
     `  ${s.bold('EXAMPLES')}`,
@@ -1250,6 +1252,7 @@ export function printDoctorHelp({ stream = process.stdout } = {}) {
     `    ${s.dim('$')} ticketlens doctor --fix`,
     `    ${s.dim('$')} ticketlens doctor --profile=work`,
     `    ${s.dim('$')} ticketlens doctor --format=json`,
+    `    ${s.dim('$')} ticketlens doctor --mcp`,
     '',
   ];
   stream.write(lines.join('\n') + '\n');

package/skills/jtb/scripts/lib/mcp-handshake-checker.mjs

@@ -0,0 +1,82 @@
+/**
+ * Spawns `ticketlens mcp` as a child process and speaks one round of the
+ * MCP stdio JSON-RPC handshake to it — the same `initialize` request an AI
+ * harness sends per the MCP stdio transport spec (see mcp-server.mjs's own
+ * `initialize` handler). Pure diagnostic probe: the child is always killed
+ * before this resolves, on every path (success, timeout, or error) — never
+ * left running.
+ */
+
+import { spawn } from 'node:child_process';
+
+export const DEFAULT_HANDSHAKE_TIMEOUT_MS = 5000;
+const PROTOCOL_VERSION = '2025-11-25';
+
+/**
+ * @returns {Promise<{ok: boolean, reason?: 'spawn-error'|'timeout'|'invalid-response', error?: Error, protocolVersion?: string}>}
+ */
+export function testMcpHandshake({
+  spawnFn = spawn,
+  timeoutMs = DEFAULT_HANDSHAKE_TIMEOUT_MS,
+} = {}) {
+  return new Promise((resolve) => {
+    let settled = false;
+    let buffer = '';
+    let child;
+
+    const settle = (value) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      try { child?.kill(); } catch { /* already exited */ }
+      resolve(value);
+    };
+
+    const timer = setTimeout(() => settle({ ok: false, reason: 'timeout' }), timeoutMs);
+
+    try {
+      child = spawnFn('ticketlens', ['mcp'], { stdio: ['pipe', 'pipe', 'pipe'] });
+    } catch (error) {
+      settle({ ok: false, reason: 'spawn-error', error });
+      return;
+    }
+
+    child.on('error', (error) => settle({ ok: false, reason: 'spawn-error', error }));
+    // A write can fail asynchronously (e.g. EPIPE if the child already died) —
+    // an unhandled 'error' on a Writable stream crashes the process. The
+    // child's own 'error'/'exit' already attributes the real failure reason;
+    // this only needs to stop the crash, not settle a second time.
+    child.stdin.on('error', () => {});
+
+    child.stdout.on('data', (chunk) => {
+      buffer += chunk.toString();
+      const newlineIdx = buffer.indexOf('\n');
+      if (newlineIdx === -1) return;
+      const line = buffer.slice(0, newlineIdx);
+      let msg;
+      try {
+        msg = JSON.parse(line);
+      } catch {
+        settle({ ok: false, reason: 'invalid-response' });
+        return;
+      }
+      if (msg?.id === 1 && msg.result?.protocolVersion) {
+        settle({ ok: true, protocolVersion: msg.result.protocolVersion });
+      } else {
+        settle({ ok: false, reason: 'invalid-response' });
+      }
+    });
+
+    const request = JSON.stringify({
+      jsonrpc: '2.0',
+      id: 1,
+      method: 'initialize',
+      params: {
+        protocolVersion: PROTOCOL_VERSION,
+        capabilities: {},
+        clientInfo: { name: 'ticketlens-doctor', version: '1.0' },
+      },
+    }) + '\n';
+    child.stdin.write(request);
+  });
+}

package/skills/jtb/scripts/lib/mcp-install.mjs

@@ -20,9 +20,10 @@ import { DEFAULT_CONFIG_DIR } from './config.mjs';
 import { isLicensed } from './license.mjs';
 import { createStyler } from './ansi.mjs';
 
-const ENTRY_NAME = 'ticketlens';
+export const ENTRY_NAME = 'ticketlens';
+export const DESIRED_MCP_ENTRY = { command: ENTRY_NAME, args: ['mcp'] };
 
-function readConfig(configPath) {
+export function readMcpConfig(configPath) {
   if (!existsSync(configPath)) return { ok: true, config: {} };
   let parsed;
   try {
@@ -55,7 +56,7 @@ export function mcpInstall({
   const configPath = join(cwd, '.mcp.json');
   const s = createStyler({ isTTY: stream.isTTY });
 
-  const read = readConfig(configPath);
+  const read = readMcpConfig(configPath);
   if (!read.ok) {
     stream.write(`  ${s.dim('✗')} ${read.reason}\n`);
     return { written: false, dryRun, path: configPath, reason: read.reason };
@@ -63,7 +64,7 @@ export function mcpInstall({
 
   const config = read.config;
   config.mcpServers ??= {};
-  const desired = { command: ENTRY_NAME, args: ['mcp'] };
+  const desired = DESIRED_MCP_ENTRY;
   const existing = config.mcpServers[ENTRY_NAME];
   const alreadyCorrect = existing !== undefined && JSON.stringify(existing) === JSON.stringify(desired);
   config.mcpServers[ENTRY_NAME] = desired;

package/skills/jtb/scripts/lib/mcp-server.mjs

@@ -31,7 +31,7 @@ const PROTOCOL_VERSION = '2025-11-25';
 const TOOLS = [
   {
     name: 'doctor',
-    description: 'Diagnose common TicketLens problems: profile configuration, license freshness, tracker connectivity, attachment cache health, and the Recall sync queue. Always returns structured JSON. Free tier, fully unrestricted — including fix.',
+    description: 'Diagnose common TicketLens problems: profile configuration, license freshness, tracker connectivity, attachment cache health, MCP registration, and the Recall sync queue. Always returns structured JSON. Free tier, fully unrestricted — including fix.',
     inputSchema: {
       type: 'object',
       properties: {