ticketlens 0.38.21 → 0.38.23

package/README.md

@@ -529,11 +529,12 @@ A one-line summary footer is also appended automatically to `ticketlens triage`
 ### Doctor
 
 ```bash
-ticketlens doctor                        # Diagnose profile/license/connectivity/cache/queue problems
-ticketlens doctor --fix                  # Attempt safe automatic fixes (license revalidation, corrupt cache cleanup, queue flush)
+ticketlens doctor                        # Diagnose profile/license/connectivity/cache/MCP-registration/queue problems
+ticketlens doctor --fix                  # Attempt safe automatic fixes (license revalidation, corrupt cache cleanup, MCP registration, queue flush)
 ticketlens doctor --profile=acme         # Scope checks to a single profile
 ticketlens doctor --format=json          # JSON output for scripting/piping
 ticketlens doctor --format=json | jq '.ok'
+ticketlens doctor --mcp                  # Also check the MCP server handshake (spawns a subprocess)
 ```
 
 Runs five checks — profile configuration, license freshness, tracker connectivity, attachment cache health, and the Recall sync queue — and reports pass/fail with an actionable hint per failure, instead of a raw stack trace. Free tier, fully unrestricted; no license required.
@@ -817,10 +818,11 @@ ticketlens stats --days=14                   # Extend lookback window (Pro, max
 ticketlens stats --format=json               # JSON output for scripting
 
 # ── Doctor ────────────────────────────────────────────────────────────────────
-ticketlens doctor                             # Diagnose profile/license/connectivity/cache/queue problems
+ticketlens doctor                             # Diagnose profile/license/connectivity/cache/MCP-registration/queue problems
 ticketlens doctor --fix                       # Attempt safe automatic fixes
 ticketlens doctor --profile=acme             # Scope checks to a single profile
 ticketlens doctor --format=json               # JSON output for scripting/piping
+ticketlens doctor --mcp                       # Also check the MCP server handshake (spawns a subprocess)
 
 # ── Compliance ────────────────────────────────────────────────────────────────
 ticketlens compliance <TICKET-KEY>            # Check ticket requirements against local diff [Pro/Free 3/mo]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ticketlens",
-  "version": "0.38.21",
+  "version": "0.38.23",
   "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/SKILL.md

@@ -1,4 +1,4 @@
-<!-- jtb-skill-version: 0.34.0 -->
+<!-- jtb-skill-version: 0.34.1 -->
 ---
 name: jtb
 description: Fetch a Jira ticket's full context (description, comments, linked issues, code references) and assemble a structured TicketBrief for implementation planning. Use when user types /jtb, mentions a Jira ticket key, or wants to plan work from a Jira ticket.
@@ -314,16 +314,17 @@ Requires a Pro license — on Free, all seven no-op with an upgrade hint on stde
 
 ## Doctor — diagnose local/tracker problems (Free)
 
-`ticketlens doctor` runs five fixed checks — profile configuration, license freshness, tracker connectivity, attachment cache health, and the Recall sync queue — and returns a pass/fail report with an actionable hint per failure, instead of a raw stack trace. Free tier, fully unrestricted; nothing here is gated.
+`ticketlens doctor` runs six fixed checks by default — profile configuration, license freshness, tracker connectivity, attachment cache health, MCP registration, and the Recall sync queue — and returns a pass/fail report with an actionable hint per failure, instead of a raw stack trace. Pass `--mcp` to also run a seventh, opt-in check: a real MCP server handshake (spawns `ticketlens mcp`, confirms it answers the JSON-RPC `initialize` request). Free tier, fully unrestricted; nothing here is gated.
 
 ```bash
-ticketlens doctor                    # run all checks
-ticketlens doctor --fix              # attempt safe automatic fixes (license revalidation, corrupt cache cleanup, queue flush)
+ticketlens doctor                    # run the six default checks
+ticketlens doctor --fix              # attempt safe automatic fixes (license revalidation, corrupt cache cleanup, MCP registration, queue flush)
 ticketlens doctor --profile=acme     # scope checks to a single profile
 ticketlens doctor --format=json      # structured output for scripting/piping
+ticketlens doctor --mcp              # also check the MCP server handshake (spawns a subprocess)
 ```
 
-If this harness has TicketLens's MCP server configured (a tool named `doctor` — often shown as `mcp__ticketlens__doctor` — visible in your tool list), prefer it over the bash form: it always requests the JSON report internally and returns it as the tool's text content, so you get a structured result to reason over directly instead of parsing CLI stdout. It accepts the same `fix`/`profile` options as the CLI flags above.
+If this harness has TicketLens's MCP server configured (a tool named `doctor` — often shown as `mcp__ticketlens__doctor` — visible in your tool list), prefer it over the bash form: it always requests the JSON report internally and returns it as the tool's text content, so you get a structured result to reason over directly instead of parsing CLI stdout. It accepts the same `fix`/`profile` options as the CLI flags above (the `--mcp` handshake check is CLI-only — deliberately not exposed as an MCP tool option, since a successful MCP tool call already proves the handshake works).
 
 A report with `ok: false` is a successful tool call describing failures, not a tool error — read the `checks[]` array for what's failing and act on each entry's `hint`, don't treat the call itself as having failed.
 

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

@@ -10,8 +10,8 @@ import { getVersion } from './config.mjs';
 const ANSI_RE = /\x1b\[[0-9;]*m/g;
 const visibleLength = (str) => str.replace(ANSI_RE, '').length;
 
-const SPINNER_FRAMES = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
-const SPINNER_INTERVAL = 80;
+export const SPINNER_FRAMES = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
+export const SPINNER_INTERVAL = 80;
 
 
 function buildBox(lines, { s, borderColor = 'cyan' }) {

package/skills/jtb/scripts/lib/connection-tester.mjs

@@ -23,6 +23,22 @@ export async function testConnections({
   for (const name of names) {
     const profile = config.profiles[name];
     const profileCreds = creds[name] || {};
+
+    if (!profileCreds.apiToken && !profileCreds.pat) {
+      // No point attempting a network call with no credentials — but still
+      // drive the session through spin()/failed()/footer() so callers that
+      // render `stream` live (e.g. onboarding.mjs's "Test connections" menu
+      // item, which discards this function's return value and relies
+      // entirely on stream output for user feedback) don't go silent.
+      const session = createSession({ baseUrl: profile.baseUrl, profileName: name, email: profile.email || undefined }, { stream });
+      const hint = `Run \`ticketlens config --profile=${name}\` to add an API token or PAT.`;
+      session.spin('Testing connection...');
+      session.failed();
+      session.footer('No credentials stored.', 'error', hint);
+      results.push({ name, ok: false, error: 'No credentials stored.', hint });
+      continue;
+    }
+
     const conn = {
       baseUrl: profile.baseUrl,
       auth: profile.auth,

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

@@ -131,6 +131,14 @@ export async function checkConnectivity({
       };
     }
     const creds = loadCredentialsFn(configDir)[profile.name] || {};
+    if (!creds.apiToken && !creds.pat) {
+      return {
+        id: 'connectivity', label: 'Tracker connectivity', ok: false,
+        message: `Profile "${profile.name}" has no credentials stored.`,
+        hint: `Run \`ticketlens config --profile=${profile.name}\` to add an API token or PAT.`,
+        fixable: false,
+      };
+    }
     const conn = {
       baseUrl: profile.baseUrl, auth: profile.auth, email: profile.email,
       apiToken: creds.apiToken, pat: creds.pat, allowPrivateIp: profile.allowPrivateIp,

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

@@ -8,6 +8,7 @@ import fs from 'node:fs';
 import { DEFAULT_CONFIG_DIR } from './config.mjs';
 import { handleUnknownFlags } from './arg-validator.mjs';
 import { createStyler } from './ansi.mjs';
+import { SPINNER_FRAMES, SPINNER_INTERVAL } from './banner.mjs';
 import {
   checkProfileConfig, checkLicenseFreshness, checkConnectivity,
   checkCacheHealth, checkRecallQueue, checkMcpRegistration, checkMcpHandshake,
@@ -25,23 +26,32 @@ const NOOP_STREAM = { write: () => true };
 // (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 });
-  stream.write('\n');
-  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) {
-      for (const line of check.hint.split('\n')) stream.write(`      ${s.dim(line)}\n`);
-    }
+function renderCheckRow(check, s) {
+  const icon = check.ok ? s.green('✔') : s.red('✖');
+  let text = `  ${icon} ${check.label}: ${check.message}\n`;
+  if (!check.ok && check.hint) {
+    for (const line of check.hint.split('\n')) text += `      ${s.dim(line)}\n`;
   }
+  return text;
+}
+
+function renderTrailer({ fixed, skipped }, s) {
+  let text = '';
   if (fixed.length > 0) {
-    stream.write(`\n  ${s.green('Fixed:')} ${fixed.join(', ')}\n`);
+    text += `\n  ${s.green('Fixed:')} ${fixed.join(', ')}\n`;
   }
   if (skipped.length > 0) {
-    stream.write(`\n  ${s.yellow('Skipped:')}\n`);
-    for (const sk of skipped) stream.write(`    ${sk.id}: ${sk.reason}\n`);
+    text += `\n  ${s.yellow('Skipped:')}\n`;
+    for (const sk of skipped) text += `    ${sk.id}: ${sk.reason}\n`;
   }
+  return text;
+}
+
+function renderPlain(checks, { fixed, skipped, stream }) {
+  const s = createStyler({ isTTY: stream.isTTY });
+  stream.write('\n');
+  for (const check of checks) stream.write(renderCheckRow(check, s));
+  stream.write(renderTrailer({ fixed, skipped }, s));
   stream.write('\n');
 }
 
@@ -142,14 +152,52 @@ export async function runDoctor(args, {
   ];
 
   const showProgress = format === 'plain' && stream.isTTY;
-  const s = createStyler({ isTTY: stream.isTTY });
+  const loaderStyler = createStyler({ isTTY: stream.isTTY });
+  const outStyler = createStyler({ isTTY: out.isTTY });
   const rawResults = [];
-  for (const { label, run } of checkList) {
-    if (showProgress) stream.write(`  ${s.dim(`○ Checking ${lowerFirst(label)}…`)}\n`);
-    try {
-      rawResults.push(await run());
-    } finally {
-      if (showProgress) stream.write('\x1b[A\r\x1b[2K');
+
+  const writeSpinnerLine = (label, frame) => {
+    stream.write(`  ${loaderStyler.brand(SPINNER_FRAMES[frame])} ${loaderStyler.dim(`Checking ${lowerFirst(label)}…`)}\n`);
+  };
+
+  // Ctrl+C during a slow check (e.g. tracker connectivity) must not leave the
+  // user's real terminal cursor permanently hidden — Node's default SIGINT
+  // handling terminates before pending finally blocks on an in-flight await
+  // run, so this needs its own listener. Same pattern as init-wizard.mjs.
+  const onSigint = () => { stream.write('\x1b[?25h'); process.exit(130); };
+  if (showProgress) {
+    out.write('\n');
+    stream.write('\x1b[?25l'); // hide cursor for the whole check-running phase
+    process.on('SIGINT', onSigint);
+  }
+  try {
+    for (const { label, run } of checkList) {
+      let frame = 0;
+      let timer;
+      if (showProgress) {
+        writeSpinnerLine(label, frame);
+        timer = setInterval(() => {
+          frame = (frame + 1) % SPINNER_FRAMES.length;
+          stream.write('\x1b[A\r\x1b[2K');
+          writeSpinnerLine(label, frame);
+        }, SPINNER_INTERVAL);
+      }
+      let result;
+      try {
+        result = await run();
+      } finally {
+        if (showProgress) {
+          clearInterval(timer);
+          stream.write('\x1b[A\r\x1b[2K');
+        }
+      }
+      rawResults.push(result);
+      if (showProgress) out.write(renderCheckRow(result, outStyler));
+    }
+  } finally {
+    if (showProgress) {
+      stream.write('\x1b[?25h'); // restore cursor
+      process.removeListener('SIGINT', onSigint);
     }
   }
 
@@ -177,6 +225,15 @@ export async function runDoctor(args, {
     return { ok };
   }
 
-  renderPlain(checks, { fixed, skipped, stream: out });
+  if (showProgress) {
+    // Rows already streamed to `out` progressively during the check loop
+    // (each check's raw, first-observed state — a later `--fix` never
+    // rewrites an already-shown row; the trailing Fixed:/Skipped: block
+    // below is the sole signal of what got repaired).
+    out.write(renderTrailer({ fixed, skipped }, outStyler));
+    out.write('\n');
+  } else {
+    renderPlain(checks, { fixed, skipped, stream: out });
+  }
   return { ok };
 }

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

@@ -1240,6 +1240,7 @@ export function printDoctorHelp({ stream = process.stdout } = {}) {
     `  ${s.bold('OPTIONS')}`,
     '',
     `    ${s.brand('--fix')}              Attempt safe, non-destructive repairs for failing checks`,
+    `                       ${s.dim('(rows show pre-fix status; see the Fixed: summary for what was repaired)')}`,
     `    ${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`,