@clankmates/cli 0.3.0 → 0.3.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clankmates/cli",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "devDependencies": {
     "@types/bun": "1.3.10",
     "typescript": "^5.9.3"

package/src/commands/doctor.ts

@@ -61,6 +61,13 @@ export async function runDoctorCommand(
     ),
   ]);
 
+  const channelDiagnostics = await maybeFetchChannelDiagnostics({
+    context,
+    requestedChannel,
+    channelResolution,
+    ownerReadReady: ownerReadTokenCheck.ok,
+  });
+
   const checks: DoctorCheck[] = [
     {
       name: "config_file",
@@ -121,6 +128,15 @@ export async function runDoctorCommand(
         ? "A publish-capable token is available for the requested channel."
         : "No publish-capable token is available for the requested channel.",
     });
+    checks.push({
+      name: "channel_diagnostics",
+      ok: channelDiagnostics.ok,
+      required: false,
+      source: channelResolution.channelId ?? requestedChannel,
+      detail:
+        channelDiagnostics.error ??
+        formatChannelDiagnosticsDetail(channelDiagnostics.value),
+    });
   }
 
   const publishReady = requestedChannel
@@ -135,6 +151,7 @@ export async function runDoctorCommand(
     requestedChannel,
     channelResolutionOk: channelResolution.ok,
     publishReady,
+    channelDiagnosticsOk: channelDiagnostics.ok,
   });
 
   printValue(io, context.outputMode, {
@@ -175,6 +192,21 @@ export async function runDoctorCommand(
     publishTokenAvailable: Boolean(resolvedPublishToken?.token),
     publishTokenSource: resolvedPublishToken?.source ?? "none",
     publishReady,
+    channelDiagnosticsAvailable: channelDiagnostics.ok,
+    channelDiagnosticsError: channelDiagnostics.error ?? "",
+    channelSummary: formatChannelSummary(channelDiagnostics.value),
+    channelStateCodes: channelDiagnostics.value?.state_codes ?? [],
+    channelStateLabels: channelDiagnostics.value?.state_labels ?? [],
+    channelActivePublishKeyCount:
+      channelDiagnostics.value?.active_publish_key_count ?? 0,
+    channelLastPostedAt: channelDiagnostics.value?.last_posted_at ?? "",
+    channelPostingPausedUntil: channelDiagnostics.value?.posting_paused_until ?? "",
+    channelLatestBlockedWriteAt:
+      channelDiagnostics.value?.latest_blocked_write_at ?? "",
+    channelLatestBlockedWriteReason:
+      channelDiagnostics.value?.latest_blocked_write_reason ?? "",
+    channelLatestBlockedWriteReasonLabel:
+      channelDiagnostics.value?.latest_blocked_write_reason_label ?? "",
     checks,
     suggestions,
   });
@@ -240,6 +272,7 @@ function buildSuggestions(input: {
   requestedChannel?: string;
   channelResolutionOk: boolean;
   publishReady: boolean;
+  channelDiagnosticsOk: boolean;
 }): string[] {
   const suggestions: string[] = [];
 
@@ -263,5 +296,93 @@ function buildSuggestions(input: {
     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}.`;
+}

package/src/lib/client.ts

@@ -15,6 +15,7 @@ import type {
   AccessKeyRevokeResponse,
   AccessKeyScope,
   ChannelAttributes,
+  ChannelDiagnosticsResponse,
   ChannelKeyAttributes,
   ChannelKeyIssueResponse,
   ChannelKeyRevokeResponse,
@@ -156,6 +157,15 @@ export class ClankmatesClient {
     );
   }
 
+  async getChannelDiagnostics(channelId: string) {
+    return this.requestAction<ChannelDiagnosticsResponse>(
+      `${API_PREFIX}/channels/${channelId}/diagnostics`,
+      {
+        token: requireOwnerReadToken(this.profile),
+      },
+    );
+  }
+
   async getChannelByName(channelName: string) {
     return this.requestResource<ChannelAttributes>(
       `${API_PREFIX}/channels/by-name/${encodeURIComponent(channelName)}`,

package/src/types/api.ts

@@ -153,3 +153,19 @@ export interface ChannelPublicationResponse {
   name: string;
   publicly_listed: boolean;
 }
+
+export interface ChannelDiagnosticsResponse {
+  channel_id: string;
+  channel_name: string;
+  channel_description?: string | null;
+  active_publish_key_count: number;
+  last_posted_at?: string | null;
+  posting_paused_until?: string | null;
+  latest_blocked_write_at?: string | null;
+  latest_blocked_write_reason?: string | null;
+  latest_blocked_write_reason_label?: string | null;
+  recent_post_window_days: number;
+  recent_block_window_hours: number;
+  state_codes: string[];
+  state_labels: string[];
+}