@clankmates/cli 0.11.1 → 0.13.0

package/src/commands/channel.ts

@@ -6,32 +6,20 @@ import {
   stringFlag,
   type ParsedArgs,
 } from "../lib/args";
-import { storeChannelToken, updateProfile } from "../lib/config";
 import { createCommandContext } from "../lib/context";
 import { CliError } from "../lib/errors";
+import { printValue, type Io } from "../lib/output";
 import {
-  joinBlocks,
-  renderFields,
-  renderPagination,
-  renderTokenAction,
-} from "../lib/human";
-import { printJson, printValue, type Io } from "../lib/output";
-import { paginatedJson, paginationInfo } from "../lib/pagination";
-import type {
-  ChannelAttributes,
-  ChannelDiagnosticsResponse,
-  ChannelKeyAttributes,
-  ChannelKeyIssueResponse,
-  ChannelKeyRevokeResponse,
-  ChannelPinResponse,
-  ChannelPublicationResponse,
-  IdResponse,
-  ShareTokenResponse,
-} from "../types/api";
-
-const CHANNEL_NAME_PATTERN = /^[a-z0-9][a-z0-9_-]*$/;
-const CHANNEL_NAME_ERROR =
-  "Channel names must start with a lowercase letter or digit and then use only lowercase letters, digits, hyphens, or underscores.";
+  formatChannelDiagnostics,
+  formatChannelRecord,
+  printChannelCollection,
+  renderChannelPinAction,
+  renderChannelPublicationAction,
+  renderIdAction,
+  renderShareToken,
+} from "./channel/render";
+import { runChannelTokenCommand } from "./channel/tokens";
+import { assertValidChannelName } from "./channel/validation";
 
 export async function runChannelCommand(
   args: ParsedArgs,
@@ -305,320 +293,3 @@ export async function runChannelCommand(
       throw new CliError("Unknown channel subcommand", 2);
   }
 }
-
-async function runChannelTokenCommand(
-  args: ParsedArgs,
-  io: Io,
-): Promise<void> {
-  const context = await createCommandContext(args, io);
-  const tokenCommand = requiredPositional(
-    args.positionals,
-    1,
-    "Missing channel token subcommand",
-  );
-
-  switch (tokenCommand) {
-    case "list": {
-      const channelId = await context.client.resolveChannelId(
-        requiredPositional(args.positionals, 2, "Missing channel"),
-      );
-      const response = await context.client.listChannelKeys({
-        channelId,
-        limit: integerFlag(args.flags, "limit", { label: "--limit" }),
-        cursor: stringFlag(args.flags, "cursor"),
-      });
-
-      if (context.outputMode === "json") {
-        printJson(
-          io,
-          paginatedJson(args, {
-            items: response.items,
-            nextCursor: response.nextCursor,
-          }),
-        );
-        return;
-      }
-
-      printValue(
-        io,
-        context.outputMode,
-        response.items.map((item) => formatChannelKeyRow(item)),
-      );
-      const pagination = paginationInfo(args, response.nextCursor);
-      const message = renderPagination(
-        pagination?.nextCursor,
-        pagination?.nextCommand,
-      );
-
-      if (message) {
-        io.stdout(message);
-      }
-      return;
-    }
-
-    case "issue": {
-      const channelId = await context.client.resolveChannelId(
-        requiredPositional(args.positionals, 2, "Missing channel"),
-      );
-      const response = await context.client.issueChannelKey({
-        channelId,
-        name: requiredStringFlag(args.flags, "name"),
-      });
-
-      await maybeStoreChannelToken(
-        args,
-        response,
-        channelId,
-        context.profileName,
-        context.configPath,
-      );
-
-      if (booleanFlag(args.flags, "tokenOnly")) {
-        io.stdout(response.token);
-        return;
-      }
-
-      printValue(
-        io,
-        context.outputMode,
-        context.outputMode === "json"
-          ? response
-          : renderChannelKeyIssue("Issued channel token", response),
-      );
-      return;
-    }
-
-    case "revoke": {
-      const response = await context.client.revokeChannelKey(
-        requiredPositional(args.positionals, 2, "Missing channel key id"),
-      );
-      await pruneInvalidStoredChannelTokens(
-        context.profileName,
-        context.profile.channelTokens,
-        context.client,
-        context.configPath,
-      );
-
-      printValue(
-        io,
-        context.outputMode,
-        context.outputMode === "json"
-          ? response
-          : renderChannelKeyRevoke("Revoked channel token", response),
-      );
-      return;
-    }
-
-    default:
-      throw new CliError("Unknown channel token subcommand", 2);
-  }
-}
-
-async function maybeStoreChannelToken(
-  args: ParsedArgs,
-  response: ChannelKeyIssueResponse,
-  channelId: string,
-  profileName: string,
-  configPath: string,
-): Promise<void> {
-  if (!booleanFlag(args.flags, "save")) {
-    return;
-  }
-
-  await storeChannelToken(profileName, channelId, response.token, configPath);
-}
-
-function printChannelCollection(
-  args: ParsedArgs,
-  outputMode: "json" | "table",
-  io: Io,
-  response: {
-    items: Array<{ id: string; attributes: ChannelAttributes }>;
-    nextCursor?: string;
-  },
-): void {
-  if (outputMode === "json") {
-    printJson(
-      io,
-      paginatedJson(args, {
-        items: response.items,
-        nextCursor: response.nextCursor,
-      }),
-    );
-    return;
-  }
-
-  printValue(
-    io,
-    outputMode,
-    response.items.map((item) => formatChannelRow(item)),
-  );
-  const pagination = paginationInfo(args, response.nextCursor);
-  const message = renderPagination(
-    pagination?.nextCursor,
-    pagination?.nextCommand,
-  );
-
-  if (message) {
-    io.stdout(message);
-  }
-}
-
-function formatChannelRecord(channel: { id: string; attributes: ChannelAttributes }) {
-  return {
-    id: channel.id,
-    name: channel.attributes.name,
-    visibility: channel.attributes.visibility,
-    publiclyListed: channel.attributes.publicly_listed ?? false,
-    description: channel.attributes.description ?? "",
-    postingPausedUntil: channel.attributes.posting_paused_until ?? "",
-    pinnedPostId: channel.attributes.pinned_post_id ?? "",
-    insertedAt: channel.attributes.inserted_at ?? "",
-    updatedAt: channel.attributes.updated_at ?? "",
-  };
-}
-
-function formatChannelDiagnostics(diagnostics: ChannelDiagnosticsResponse) {
-  return {
-    channelId: diagnostics.channel_id,
-    channelName: diagnostics.channel_name,
-    channelDescription: diagnostics.channel_description ?? "",
-    stateLabels: diagnostics.state_labels.join(", "),
-    activePublishKeyCount: diagnostics.active_publish_key_count,
-    lastPostedAt: diagnostics.last_posted_at ?? "",
-    postingPausedUntil: diagnostics.posting_paused_until ?? "",
-    latestBlockedWriteAt: diagnostics.latest_blocked_write_at ?? "",
-    latestBlockedWriteReason:
-      diagnostics.latest_blocked_write_reason_label ??
-      diagnostics.latest_blocked_write_reason ??
-      "",
-  };
-}
-
-function formatChannelRow(channel: { id: string; attributes: ChannelAttributes }) {
-  return {
-    id: channel.id,
-    name: channel.attributes.name,
-    visibility: channel.attributes.visibility,
-    publiclyListed: channel.attributes.publicly_listed ?? false,
-    pinnedPostId: channel.attributes.pinned_post_id ?? "",
-    description: channel.attributes.description ?? "",
-  };
-}
-
-function formatChannelKeyRow(item: { id: string; attributes: ChannelKeyAttributes }) {
-  return {
-    id: item.id,
-    name: item.attributes.name ?? "",
-    expiresAt: item.attributes.expires_at ?? "",
-    revokedAt: item.attributes.revoked_at ?? "",
-    issuedAt: item.attributes.inserted_at ?? "",
-  };
-}
-
-function renderShareToken(title: string, response: ShareTokenResponse): string {
-  return joinBlocks([
-    title,
-    renderFields([["Token", response.token]]),
-  ]);
-}
-
-function renderIdAction(title: string, response: IdResponse): string {
-  return joinBlocks([
-    title,
-    renderFields([["ID", response.id]]),
-  ]);
-}
-
-function renderChannelPublicationAction(
-  title: string,
-  response: ChannelPublicationResponse,
-): string {
-  return joinBlocks([
-    title,
-    renderFields([
-      ["ID", response.id],
-      ["Name", response.name],
-      ["Publicly listed", response.publicly_listed],
-    ]),
-  ]);
-}
-
-function renderChannelPinAction(
-  title: string,
-  response: ChannelPinResponse,
-): string {
-  const channel = Array.isArray(response.data)
-    ? response.data[0]
-    : response.data;
-
-  return joinBlocks([
-    title,
-    renderFields([
-      ["Channel", channel?.attributes.name ?? ""],
-      ["Pinned post", channel?.attributes.pinned_post_id ?? ""],
-    ]),
-  ]);
-}
-
-function renderChannelKeyIssue(
-  title: string,
-  response: ChannelKeyIssueResponse,
-): string {
-  return renderTokenAction({
-    title,
-    id: response.id,
-    name: response.name,
-    token: response.token,
-    issuedAt: response.issued_at,
-    expiresAt: response.expires_at,
-  });
-}
-
-function renderChannelKeyRevoke(
-  title: string,
-  response: ChannelKeyRevokeResponse,
-): string {
-  return joinBlocks([
-    title,
-    renderFields([
-      ["ID", response.id],
-      ["Name", response.name],
-    ]),
-  ]);
-}
-
-async function pruneInvalidStoredChannelTokens(
-  profileName: string,
-  storedTokens: Record<string, { token: string }>,
-  client: Awaited<ReturnType<typeof createCommandContext>>["client"],
-  configPath: string,
-): Promise<void> {
-  const invalidChannelIds: string[] = [];
-
-  for (const [channelId, storedToken] of Object.entries(storedTokens)) {
-    if (!(await client.canAuthenticate(storedToken.token))) {
-      invalidChannelIds.push(channelId);
-    }
-  }
-
-  if (invalidChannelIds.length === 0) {
-    return;
-  }
-
-  await updateProfile(
-    profileName,
-    (profile) => {
-      for (const channelId of invalidChannelIds) {
-        delete profile.channelTokens[channelId];
-      }
-    },
-    configPath,
-  );
-}
-
-function assertValidChannelName(name: string): void {
-  if (!CHANNEL_NAME_PATTERN.test(name)) {
-    throw new CliError(CHANNEL_NAME_ERROR, 2);
-  }
-}

package/src/commands/doctor/checks.ts

@@ -0,0 +1,123 @@
+import { access } from "node:fs/promises";
+
+import type {
+  ChannelDiagnostics,
+  ChannelDiagnosticsResult,
+  ChannelResolution,
+  CheckResult,
+  DoctorContext,
+} from "./types";
+
+export 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;
+  }
+}
+
+export async function resolveRequestedChannel(
+  context: DoctorContext,
+  channel: string,
+): Promise<ChannelResolution> {
+  try {
+    return {
+      ok: true,
+      channelId: await context.client.resolveChannelId(channel),
+    };
+  } catch (error) {
+    return {
+      ok: false,
+      error: (error as Error).message,
+    };
+  }
+}
+
+export async function runOptionalCheck(
+  token: string | undefined,
+  operation: (token: string) => Promise<unknown>,
+  missingMessage: string,
+): Promise<CheckResult> {
+  if (!token) {
+    return { ok: false, error: missingMessage };
+  }
+
+  return runCheck(() => operation(token));
+}
+
+export async function runCheck(
+  operation: () => Promise<unknown>,
+): Promise<CheckResult> {
+  try {
+    await operation();
+    return { ok: true };
+  } catch (error) {
+    return { ok: false, error: (error as Error).message };
+  }
+}
+
+export async function maybeFetchChannelDiagnostics(input: {
+  context: DoctorContext;
+  requestedChannel?: string;
+  channelResolution: ChannelResolution;
+  ownerReadReady: boolean;
+}): Promise<ChannelDiagnosticsResult> {
+  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,
+    };
+  }
+}
+
+export function formatChannelSummary(
+  diagnostics: ChannelDiagnostics | undefined,
+): string {
+  if (!diagnostics || diagnostics.state_labels.length === 0) {
+    return "";
+  }
+
+  return diagnostics.state_labels.join(", ");
+}
+
+export function formatChannelDiagnosticsDetail(
+  diagnostics: ChannelDiagnostics | undefined,
+): string {
+  const summary = formatChannelSummary(diagnostics);
+
+  if (!summary) {
+    return "Channel diagnostics are unavailable.";
+  }
+
+  return `Channel diagnostics loaded successfully: ${summary}.`;
+}

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;
+}