@clankmates/cli 0.2.0 → 0.3.1

package/src/commands/channel.ts

@@ -1,14 +1,20 @@
 import {
   booleanFlag,
+  integerFlag,
   requiredPositional,
   requiredStringFlag,
   stringFlag,
   type ParsedArgs,
 } from "../lib/args";
-import { storeChannelToken } from "../lib/config";
+import { storeChannelToken, updateProfile } from "../lib/config";
 import { createCommandContext } from "../lib/context";
 import { CliError } from "../lib/errors";
 import { printJson, printValue, type Io } from "../lib/output";
+import type {
+  ChannelAttributes,
+  ChannelKeyAttributes,
+  ChannelKeyIssueResponse,
+} from "../types/api";
 
 const CHANNEL_NAME_PATTERN = /^[a-z0-9][a-z0-9_-]*$/;
 const CHANNEL_NAME_ERROR =
@@ -23,23 +29,12 @@ export async function runChannelCommand(
 
   switch (subcommand) {
     case "list": {
-      const response = await context.client.listChannels();
-      const rows = response.items.map((item) => ({
-        id: item.id,
-        name: item.attributes.name,
-        visibility: item.attributes.visibility,
-        description: item.attributes.description ?? "",
-      }));
-
-      if (context.outputMode === "json") {
-        printJson(io, {
-          items: response.items,
-          nextCursor: response.nextCursor,
-        });
-        return;
-      }
+      const response = await context.client.listChannels({
+        limit: integerFlag(args.flags, "limit", { label: "--limit" }),
+        cursor: stringFlag(args.flags, "cursor"),
+      });
 
-      printValue(io, context.outputMode, rows);
+      printChannelCollection(context.outputMode, io, response);
       return;
     }
 
@@ -51,15 +46,45 @@ export async function runChannelCommand(
       printValue(
         io,
         context.outputMode,
-        context.outputMode === "json"
-          ? channel
-          : {
-              id: channel.id,
-              name: channel.attributes.name,
-              visibility: channel.attributes.visibility,
-              description: channel.attributes.description ?? "",
-              postingPausedUntil: channel.attributes.posting_paused_until ?? "",
-            },
+        context.outputMode === "json" ? channel : formatChannelRecord(channel),
+      );
+      return;
+    }
+
+    case "public-list": {
+      const response = await context.client.listPublicChannelsForHandle({
+        handle: requiredPositional(args.positionals, 1, "Missing public handle"),
+        limit: integerFlag(args.flags, "limit", { label: "--limit" }),
+        cursor: stringFlag(args.flags, "cursor"),
+      });
+
+      printChannelCollection(context.outputMode, io, response);
+      return;
+    }
+
+    case "public-get": {
+      const channel = await context.client.getPublicChannelByHandle(
+        requiredPositional(args.positionals, 1, "Missing public handle"),
+        requiredPositional(args.positionals, 2, "Missing public channel name"),
+      );
+
+      printValue(
+        io,
+        context.outputMode,
+        context.outputMode === "json" ? channel : formatChannelRecord(channel),
+      );
+      return;
+    }
+
+    case "shared-get": {
+      const channel = await context.client.getSharedChannel(
+        requiredPositional(args.positionals, 1, "Missing share token"),
+      );
+
+      printValue(
+        io,
+        context.outputMode,
+        context.outputMode === "json" ? channel : formatChannelRecord(channel),
       );
       return;
     }
@@ -76,14 +101,7 @@ export async function runChannelCommand(
       printValue(
         io,
         context.outputMode,
-        context.outputMode === "json"
-          ? channel
-          : {
-              id: channel.id,
-              name: channel.attributes.name,
-              visibility: channel.attributes.visibility,
-              description: channel.attributes.description ?? "",
-            },
+        context.outputMode === "json" ? channel : formatChannelRecord(channel),
       );
       return;
     }
@@ -118,15 +136,57 @@ export async function runChannelCommand(
       printValue(
         io,
         context.outputMode,
-        context.outputMode === "json"
-          ? channel
-          : {
-              id: channel.id,
-              name: channel.attributes.name,
-              visibility: channel.attributes.visibility,
-              description: channel.attributes.description ?? "",
-            },
+        context.outputMode === "json" ? channel : formatChannelRecord(channel),
+      );
+      return;
+    }
+
+    case "publish-public": {
+      const channelId = await context.client.resolveChannelId(
+        requiredPositional(args.positionals, 1, "Missing channel"),
+      );
+      const channel = await context.client.publishChannelPublicly(channelId);
+
+      printValue(
+        io,
+        context.outputMode,
+        context.outputMode === "json" ? channel : formatChannelRecord(channel),
+      );
+      return;
+    }
+
+    case "unpublish-public": {
+      const channelId = await context.client.resolveChannelId(
+        requiredPositional(args.positionals, 1, "Missing channel"),
+      );
+      const response = await context.client.unpublishChannelPublicly(channelId);
+
+      printValue(io, context.outputMode, response);
+      return;
+    }
+
+    case "share": {
+      const channelId = await context.client.resolveChannelId(
+        requiredPositional(args.positionals, 1, "Missing channel"),
+      );
+      const response = await context.client.shareChannel(channelId);
+
+      if (booleanFlag(args.flags, "tokenOnly")) {
+        io.stdout(response.token);
+        return;
+      }
+
+      printValue(io, context.outputMode, response);
+      return;
+    }
+
+    case "revoke-share": {
+      const channelId = await context.client.resolveChannelId(
+        requiredPositional(args.positionals, 1, "Missing channel"),
       );
+      const response = await context.client.revokeChannelShare(channelId);
+
+      printValue(io, context.outputMode, response);
       return;
     }
 
@@ -146,21 +206,93 @@ export async function runChannelCommand(
       return;
     }
 
+    case "token": {
+      await runChannelTokenCommand(args, io);
+      return;
+    }
+
     case "rotate-token": {
+      const channelRef = requiredPositional(args.positionals, 1, "Missing channel");
+      const channelId = await context.client.resolveChannelId(channelRef);
+      const response = await context.client.issueChannelKey({
+        channelId,
+        name: stringFlag(args.flags, "name") ?? legacyKeyName(),
+      });
+
+      await maybeStoreChannelToken(
+        args,
+        response,
+        channelId,
+        context.profileName,
+        context.configPath,
+      );
+
+      if (booleanFlag(args.flags, "tokenOnly")) {
+        io.stdout(response.token);
+        return;
+      }
+
+      printValue(io, context.outputMode, response);
+      return;
+    }
+
+    default:
+      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, 1, "Missing channel"),
+        requiredPositional(args.positionals, 2, "Missing channel"),
       );
-      const response = await context.client.rotateChannelToken(channelId);
+      const response = await context.client.listChannelKeys({
+        channelId,
+        limit: integerFlag(args.flags, "limit", { label: "--limit" }),
+        cursor: stringFlag(args.flags, "cursor"),
+      });
 
-      if (booleanFlag(args.flags, "save")) {
-        await storeChannelToken(
-          context.profileName,
-          channelId,
-          response.token,
-          context.configPath,
-        );
+      if (context.outputMode === "json") {
+        printJson(io, { items: response.items, nextCursor: response.nextCursor });
+        return;
       }
 
+      printValue(
+        io,
+        context.outputMode,
+        response.items.map((item) => formatChannelKeyRow(item)),
+      );
+      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;
@@ -170,9 +302,127 @@ export async function runChannelCommand(
       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, response);
+      return;
+    }
+
     default:
-      throw new CliError("Unknown channel subcommand", 2);
+      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(
+  outputMode: "json" | "table",
+  io: Io,
+  response: {
+    items: Array<{ id: string; attributes: ChannelAttributes }>;
+    nextCursor?: string;
+  },
+): void {
+  if (outputMode === "json") {
+    printJson(io, {
+      items: response.items,
+      nextCursor: response.nextCursor,
+    });
+    return;
   }
+
+  printValue(
+    io,
+    outputMode,
+    response.items.map((item) => formatChannelRow(item)),
+  );
+}
+
+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 ?? "",
+    insertedAt: channel.attributes.inserted_at ?? "",
+    updatedAt: channel.attributes.updated_at ?? "",
+  };
+}
+
+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,
+    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 legacyKeyName(): string {
+  return `legacy-rotate-${new Date().toISOString()}`;
+}
+
+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 {

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