@clankmates/cli 0.12.0 → 0.13.0

package/src/commands/doctor/render.ts

@@ -0,0 +1,140 @@
+import {
+  formatTimestamp,
+  joinBlocks,
+  renderBullets,
+  renderFields,
+  renderSection,
+} from "../../lib/human";
+import type { DoctorCheck, DoctorReport } from "./types";
+
+export function renderDoctorReport(report: DoctorReport): string {
+  return joinBlocks([
+    renderSection(
+      "Status",
+      renderFields([
+        ["Result", report.status],
+        ["Summary", report.summary],
+        ["Profile", report.profile],
+        ["Base URL", report.baseUrl],
+        ["Config", report.configPath],
+        ["CLI version", report.cliVersion],
+      ]),
+    ),
+    renderSection(
+      "Auth",
+      renderFields([
+        [
+          "Master token",
+          renderTokenStatus(
+            report.hasMasterToken,
+            report.masterTokenOk,
+            report.masterTokenSource,
+            report.masterTokenError,
+          ),
+        ],
+        [
+          "Read-only token",
+          renderTokenStatus(
+            report.hasReadOnlyToken,
+            report.readOnlyTokenOk,
+            report.readOnlyTokenSource,
+            report.readOnlyTokenError,
+          ),
+        ],
+        [
+          "Owner-read token",
+          renderTokenStatus(
+            report.ownerReadTokenAvailable,
+            report.ownerReadTokenOk,
+            report.ownerReadTokenSource,
+            report.ownerReadTokenError,
+          ),
+        ],
+        ["Stored channel tokens", report.storedChannelTokens],
+      ]),
+    ),
+    report.channel
+      ? renderSection(
+          "Channel",
+          renderFields([
+            ["Requested", report.channel],
+            ["Resolved ID", report.channelId],
+            [
+              "Resolution",
+              report.channelResolutionOk ? "ok" : report.channelResolutionError,
+            ],
+            [
+              "Publish token",
+              report.publishTokenAvailable
+                ? `available (${report.publishTokenSource})`
+                : "missing",
+            ],
+            ["Publish ready", report.publishReady],
+            [
+              "Diagnostics",
+              report.channelDiagnosticsAvailable
+                ? report.channelSummary
+                : report.channelDiagnosticsError,
+            ],
+            ["Active publish keys", report.channelActivePublishKeyCount],
+            [
+              "Last posted",
+              report.channelLastPostedAt
+                ? formatTimestamp(report.channelLastPostedAt)
+                : undefined,
+            ],
+            [
+              "Paused until",
+              report.channelPostingPausedUntil
+                ? formatTimestamp(report.channelPostingPausedUntil)
+                : undefined,
+            ],
+            [
+              "Latest blocked write",
+              report.channelLatestBlockedWriteAt
+                ? formatTimestamp(report.channelLatestBlockedWriteAt)
+                : undefined,
+            ],
+            [
+              "Latest blocked reason",
+              report.channelLatestBlockedWriteReasonLabel ||
+                report.channelLatestBlockedWriteReason ||
+                undefined,
+            ],
+          ]),
+        )
+      : undefined,
+    renderSection("Checks", renderChecks(report.checks)),
+    report.suggestions.length > 0
+      ? renderSection("Suggestions", renderBullets(report.suggestions))
+      : undefined,
+  ]);
+}
+
+function renderTokenStatus(
+  configured: boolean,
+  ok: boolean,
+  source: string,
+  error: string,
+): string {
+  if (ok) {
+    return `ok (${source})`;
+  }
+
+  if (configured) {
+    return `failed (${source}): ${error}`;
+  }
+
+  return error || "missing";
+}
+
+function renderChecks(checks: DoctorCheck[]): string {
+  const rows = checks.map((check) => {
+    const status = check.ok ? "ok" : check.required ? "fail" : "warn";
+    const source = check.source ? ` [${check.source}]` : "";
+
+    return `${status.padEnd(4)} ${check.name}${source}\n  ${check.detail}`;
+  });
+
+  return rows.join("\n");
+}

package/src/commands/doctor/suggestions.ts

@@ -0,0 +1,42 @@
+export function buildSuggestions(input: {
+  configFileExists: boolean;
+  openApiOk: boolean;
+  ownerReadReady: boolean;
+  requestedChannel?: string;
+  channelResolutionOk: boolean;
+  publishReady: boolean;
+  channelDiagnosticsOk: boolean;
+}): string[] {
+  const suggestions: string[] = [];
+
+  if (!input.configFileExists) {
+    suggestions.push("Run `clankm config init` to create local config.");
+  }
+
+  if (!input.openApiOk) {
+    suggestions.push("Check `CLANKMATES_BASE_URL` or `--base-url`, then retry `clankm doctor --json`.");
+  }
+
+  if (!input.ownerReadReady) {
+    suggestions.push("Configure a read-only or master token for owner reads with `clankm auth login ...`.");
+  }
+
+  if (input.requestedChannel && !input.channelResolutionOk) {
+    suggestions.push("Use a channel UUID or configure an owner-read token so channel names can be resolved.");
+  }
+
+  if (input.requestedChannel && !input.publishReady) {
+    suggestions.push("Provide `--channel-token`, `CLANKMATES_CHANNEL_TOKEN`, `CLANKMATES_CHANNEL_TOKENS_JSON`, `CLANKMATES_CHANNEL_TOKENS_FILE`, or a master token for publish.");
+  }
+
+  if (
+    input.requestedChannel &&
+    input.channelResolutionOk &&
+    input.ownerReadReady &&
+    !input.channelDiagnosticsOk
+  ) {
+    suggestions.push("Retry the channel diagnostics with an owner-read token that can read the requested channel.");
+  }
+
+  return suggestions;
+}

package/src/commands/doctor/types.ts

@@ -0,0 +1,75 @@
+import type { createCommandContext } from "../../lib/context";
+
+export interface DoctorCheck {
+  name: string;
+  ok: boolean;
+  required: boolean;
+  source?: string;
+  detail: string;
+}
+
+export interface DoctorReport {
+  cliVersion: string;
+  ok: boolean;
+  status: "ok" | "needs_attention";
+  summary: string;
+  profile: string;
+  configPath: string;
+  configFileExists: boolean;
+  baseUrl: string;
+  hasMasterToken: boolean;
+  masterTokenSource: string;
+  masterTokenOk: boolean;
+  masterTokenError: string;
+  hasReadOnlyToken: boolean;
+  readOnlyTokenSource: string;
+  readOnlyTokenOk: boolean;
+  readOnlyTokenError: string;
+  ownerReadTokenAvailable: boolean;
+  ownerReadTokenSource: string;
+  ownerReadTokenOk: boolean;
+  ownerReadTokenError: string;
+  ownerReadReady: boolean;
+  openApiOk: boolean;
+  openApiError: string;
+  storedChannelTokens: number;
+  channel: string;
+  channelId: string;
+  channelResolutionOk: boolean;
+  channelResolutionError: string;
+  publishTokenAvailable: boolean;
+  publishTokenSource: string;
+  publishReady: boolean;
+  channelDiagnosticsAvailable: boolean;
+  channelDiagnosticsError: string;
+  channelSummary: string;
+  channelStateCodes: string[];
+  channelStateLabels: string[];
+  channelActivePublishKeyCount: number;
+  channelLastPostedAt: string;
+  channelPostingPausedUntil: string;
+  channelLatestBlockedWriteAt: string;
+  channelLatestBlockedWriteReason: string;
+  channelLatestBlockedWriteReasonLabel: string;
+  checks: DoctorCheck[];
+  suggestions: string[];
+}
+
+export type DoctorContext = Awaited<ReturnType<typeof createCommandContext>>;
+
+export type ChannelDiagnostics = Awaited<
+  ReturnType<DoctorContext["client"]["getChannelDiagnostics"]>
+>;
+
+export interface CheckResult {
+  ok: boolean;
+  error?: string;
+}
+
+export interface ChannelResolution extends CheckResult {
+  channelId?: string;
+}
+
+export interface ChannelDiagnosticsResult extends CheckResult {
+  value?: ChannelDiagnostics;
+}

package/src/commands/doctor.ts

@@ -1,14 +1,5 @@
-import { access } from "node:fs/promises";
-
 import { createCommandContext } from "../lib/context";
 import { channelFlag, type ParsedArgs } from "../lib/args";
-import {
-  formatTimestamp,
-  joinBlocks,
-  renderBullets,
-  renderFields,
-  renderSection,
-} from "../lib/human";
 import { printValue, type Io } from "../lib/output";
 import { CLI_VERSION } from "../lib/version";
 import {
@@ -17,61 +8,18 @@ import {
   resolvePublishToken,
   resolveReadOnlyToken,
 } from "../lib/tokens";
-
-interface DoctorCheck {
-  name: string;
-  ok: boolean;
-  required: boolean;
-  source?: string;
-  detail: string;
-}
-
-interface DoctorReport {
-  cliVersion: string;
-  ok: boolean;
-  status: "ok" | "needs_attention";
-  summary: string;
-  profile: string;
-  configPath: string;
-  configFileExists: boolean;
-  baseUrl: string;
-  hasMasterToken: boolean;
-  masterTokenSource: string;
-  masterTokenOk: boolean;
-  masterTokenError: string;
-  hasReadOnlyToken: boolean;
-  readOnlyTokenSource: string;
-  readOnlyTokenOk: boolean;
-  readOnlyTokenError: string;
-  ownerReadTokenAvailable: boolean;
-  ownerReadTokenSource: string;
-  ownerReadTokenOk: boolean;
-  ownerReadTokenError: string;
-  ownerReadReady: boolean;
-  openApiOk: boolean;
-  openApiError: string;
-  storedChannelTokens: number;
-  channel: string;
-  channelId: string;
-  channelResolutionOk: boolean;
-  channelResolutionError: string;
-  publishTokenAvailable: boolean;
-  publishTokenSource: string;
-  publishReady: boolean;
-  channelDiagnosticsAvailable: boolean;
-  channelDiagnosticsError: string;
-  channelSummary: string;
-  channelStateCodes: string[];
-  channelStateLabels: string[];
-  channelActivePublishKeyCount: number;
-  channelLastPostedAt: string;
-  channelPostingPausedUntil: string;
-  channelLatestBlockedWriteAt: string;
-  channelLatestBlockedWriteReason: string;
-  channelLatestBlockedWriteReasonLabel: string;
-  checks: DoctorCheck[];
-  suggestions: string[];
-}
+import {
+  checkConfigPath,
+  formatChannelDiagnosticsDetail,
+  formatChannelSummary,
+  maybeFetchChannelDiagnostics,
+  resolveRequestedChannel,
+  runCheck,
+  runOptionalCheck,
+} from "./doctor/checks";
+import { renderDoctorReport } from "./doctor/render";
+import { buildSuggestions } from "./doctor/suggestions";
+import type { DoctorCheck, DoctorReport } from "./doctor/types";
 
 export async function runDoctorCommand(
   args: ParsedArgs,
@@ -271,310 +219,3 @@ export async function runDoctorCommand(
     context.outputMode === "json" ? report : renderDoctorReport(report),
   );
 }
-
-async function checkConfigPath(configPath: string): Promise<boolean> {
-  try {
-    await access(configPath);
-    return true;
-  } catch (error) {
-    if ((error as NodeJS.ErrnoException).code === "ENOENT") {
-      return false;
-    }
-
-    return false;
-  }
-}
-
-async function resolveRequestedChannel(
-  context: Awaited<ReturnType<typeof createCommandContext>>,
-  channel: string,
-): Promise<{ ok: boolean; channelId?: string; error?: string }> {
-  try {
-    return {
-      ok: true,
-      channelId: await context.client.resolveChannelId(channel),
-    };
-  } catch (error) {
-    return {
-      ok: false,
-      error: (error as Error).message,
-    };
-  }
-}
-
-async function runOptionalCheck(
-  token: string | undefined,
-  operation: (token: string) => Promise<unknown>,
-  missingMessage: string,
-): Promise<{ ok: boolean; error?: string }> {
-  if (!token) {
-    return { ok: false, error: missingMessage };
-  }
-
-  return runCheck(() => operation(token));
-}
-
-async function runCheck(
-  operation: () => Promise<unknown>,
-): Promise<{ ok: boolean; error?: string }> {
-  try {
-    await operation();
-    return { ok: true };
-  } catch (error) {
-    return { ok: false, error: (error as Error).message };
-  }
-}
-
-function buildSuggestions(input: {
-  configFileExists: boolean;
-  openApiOk: boolean;
-  ownerReadReady: boolean;
-  requestedChannel?: string;
-  channelResolutionOk: boolean;
-  publishReady: boolean;
-  channelDiagnosticsOk: boolean;
-}): string[] {
-  const suggestions: string[] = [];
-
-  if (!input.configFileExists) {
-    suggestions.push("Run `clankm config init` to create local config.");
-  }
-
-  if (!input.openApiOk) {
-    suggestions.push("Check `CLANKMATES_BASE_URL` or `--base-url`, then retry `clankm doctor --json`.");
-  }
-
-  if (!input.ownerReadReady) {
-    suggestions.push("Configure a read-only or master token for owner reads with `clankm auth login ...`.");
-  }
-
-  if (input.requestedChannel && !input.channelResolutionOk) {
-    suggestions.push("Use a channel UUID or configure an owner-read token so channel names can be resolved.");
-  }
-
-  if (input.requestedChannel && !input.publishReady) {
-    suggestions.push("Provide `--channel-token`, `CLANKMATES_CHANNEL_TOKEN`, `CLANKMATES_CHANNEL_TOKENS_JSON`, `CLANKMATES_CHANNEL_TOKENS_FILE`, or a master token for publish.");
-  }
-
-  if (
-    input.requestedChannel &&
-    input.channelResolutionOk &&
-    input.ownerReadReady &&
-    !input.channelDiagnosticsOk
-  ) {
-    suggestions.push("Retry the channel diagnostics with an owner-read token that can read the requested channel.");
-  }
-
-  return suggestions;
-}
-
-async function maybeFetchChannelDiagnostics(input: {
-  context: Awaited<ReturnType<typeof createCommandContext>>;
-  requestedChannel?: string;
-  channelResolution: { ok: boolean; channelId?: string; error?: string };
-  ownerReadReady: boolean;
-}): Promise<{
-  ok: boolean;
-  value?: Awaited<
-    ReturnType<Awaited<ReturnType<typeof createCommandContext>>["client"]["getChannelDiagnostics"]>
-  >;
-  error?: string;
-}> {
-  if (!input.requestedChannel) {
-    return { ok: false };
-  }
-
-  if (!input.channelResolution.ok || !input.channelResolution.channelId) {
-    return {
-      ok: false,
-      error: "Channel diagnostics require a resolved channel.",
-    };
-  }
-
-  if (!input.ownerReadReady) {
-    return {
-      ok: false,
-      error: "Channel diagnostics require an owner-read token.",
-    };
-  }
-
-  try {
-    return {
-      ok: true,
-      value: await input.context.client.getChannelDiagnostics(
-        input.channelResolution.channelId,
-      ),
-    };
-  } catch (error) {
-    return {
-      ok: false,
-      error: (error as Error).message,
-    };
-  }
-}
-
-function formatChannelSummary(
-  diagnostics:
-    | Awaited<
-        ReturnType<
-          Awaited<ReturnType<typeof createCommandContext>>["client"]["getChannelDiagnostics"]
-        >
-      >
-    | undefined,
-): string {
-  if (!diagnostics || diagnostics.state_labels.length === 0) {
-    return "";
-  }
-
-  return diagnostics.state_labels.join(", ");
-}
-
-function formatChannelDiagnosticsDetail(
-  diagnostics:
-    | Awaited<
-        ReturnType<
-          Awaited<ReturnType<typeof createCommandContext>>["client"]["getChannelDiagnostics"]
-        >
-      >
-    | undefined,
-): string {
-  const summary = formatChannelSummary(diagnostics);
-
-  if (!summary) {
-    return "Channel diagnostics are unavailable.";
-  }
-
-  return `Channel diagnostics loaded successfully: ${summary}.`;
-}
-
-function renderDoctorReport(report: DoctorReport): string {
-  return joinBlocks([
-    renderSection(
-      "Status",
-      renderFields([
-        ["Result", report.status],
-        ["Summary", report.summary],
-        ["Profile", report.profile],
-        ["Base URL", report.baseUrl],
-        ["Config", report.configPath],
-        ["CLI version", report.cliVersion],
-      ]),
-    ),
-    renderSection(
-      "Auth",
-      renderFields([
-        [
-          "Master token",
-          renderTokenStatus(
-            report.hasMasterToken,
-            report.masterTokenOk,
-            report.masterTokenSource,
-            report.masterTokenError,
-          ),
-        ],
-        [
-          "Read-only token",
-          renderTokenStatus(
-            report.hasReadOnlyToken,
-            report.readOnlyTokenOk,
-            report.readOnlyTokenSource,
-            report.readOnlyTokenError,
-          ),
-        ],
-        [
-          "Owner-read token",
-          renderTokenStatus(
-            report.ownerReadTokenAvailable,
-            report.ownerReadTokenOk,
-            report.ownerReadTokenSource,
-            report.ownerReadTokenError,
-          ),
-        ],
-        ["Stored channel tokens", report.storedChannelTokens],
-      ]),
-    ),
-    report.channel
-      ? renderSection(
-          "Channel",
-          renderFields([
-            ["Requested", report.channel],
-            ["Resolved ID", report.channelId],
-            [
-              "Resolution",
-              report.channelResolutionOk ? "ok" : report.channelResolutionError,
-            ],
-            [
-              "Publish token",
-              report.publishTokenAvailable
-                ? `available (${report.publishTokenSource})`
-                : "missing",
-            ],
-            ["Publish ready", report.publishReady],
-            [
-              "Diagnostics",
-              report.channelDiagnosticsAvailable
-                ? report.channelSummary
-                : report.channelDiagnosticsError,
-            ],
-            ["Active publish keys", report.channelActivePublishKeyCount],
-            [
-              "Last posted",
-              report.channelLastPostedAt
-                ? formatTimestamp(report.channelLastPostedAt)
-                : undefined,
-            ],
-            [
-              "Paused until",
-              report.channelPostingPausedUntil
-                ? formatTimestamp(report.channelPostingPausedUntil)
-                : undefined,
-            ],
-            [
-              "Latest blocked write",
-              report.channelLatestBlockedWriteAt
-                ? formatTimestamp(report.channelLatestBlockedWriteAt)
-                : undefined,
-            ],
-            [
-              "Latest blocked reason",
-              report.channelLatestBlockedWriteReasonLabel ||
-                report.channelLatestBlockedWriteReason ||
-                undefined,
-            ],
-          ]),
-        )
-      : undefined,
-    renderSection("Checks", renderChecks(report.checks)),
-    report.suggestions.length > 0
-      ? renderSection("Suggestions", renderBullets(report.suggestions))
-      : undefined,
-  ]);
-}
-
-function renderTokenStatus(
-  configured: boolean,
-  ok: boolean,
-  source: string,
-  error: string,
-): string {
-  if (ok) {
-    return `ok (${source})`;
-  }
-
-  if (configured) {
-    return `failed (${source}): ${error}`;
-  }
-
-  return error || "missing";
-}
-
-function renderChecks(checks: DoctorCheck[]): string {
-  const rows = checks.map((check) => {
-    const status = check.ok ? "ok" : check.required ? "fail" : "warn";
-    const source = check.source ? ` [${check.source}]` : "";
-
-    return `${status.padEnd(4)} ${check.name}${source}\n  ${check.detail}`;
-  });
-
-  return rows.join("\n");
-}