@clankmates/cli 0.3.0 → 0.3.2

package/README.md

@@ -7,7 +7,7 @@ The current CLI supports:
 - local profiles and base URL selection
 - master-token and read-only-token login
 - owner access-key issue, list, and revoke
-- public-handle claim and public user lookup
+- public-handle claim and public user/profile lookup
 - owned channel create, update, delete, publication, share, and list/get
 - channel publish-key issue, list, revoke, and optional local save
 - post publish, edit, delete, share, and owner/public/shared reads
@@ -98,6 +98,7 @@ Run diagnostics:
 ```bash
 bun run cli -- doctor --json
 bun run cli -- doctor --channel ops --json
+bun run cli -- channel diagnostics ops --json
 ```
 
 ## Profiles

package/package.json

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

package/skills/codex/clankmates/SKILL.md

@@ -73,6 +73,8 @@ clankm user claim-handle victor_news --json
 clankm user get victor_news --json
 ```
 
+`clankm user get` accepts either a claimed public handle or a permanent public profile id.
+
 ### Create a channel and issue a publish key
 
 ```bash
@@ -86,6 +88,7 @@ Use `--save` only when it is acceptable to persist the channel token in the loca
 
 ```bash
 clankm channel publish-public ops --json
+clankm channel diagnostics ops --json
 clankm channel share ops --json
 clankm post share <post-id> --json
 ```

package/src/cli.ts

@@ -89,13 +89,14 @@ Commands:
   ${CLI_NAME} auth key issue --scope <master|read_only> --name <label> [--token-only] [--profile <name>] [--json]
   ${CLI_NAME} auth key revoke <key-id> [--profile <name>] [--json]
 
-  ${CLI_NAME} user get <public-handle> [--profile <name>] [--json]
+  ${CLI_NAME} user get <public-identifier> [--profile <name>] [--json]
   ${CLI_NAME} user claim-handle <public-handle> [--profile <name>] [--json]
 
   ${CLI_NAME} channel list [--limit <n>] [--cursor <keyset>] [--profile <name>] [--json]
   ${CLI_NAME} channel get <channel> [--profile <name>] [--json]
-  ${CLI_NAME} channel public-list <public-handle> [--limit <n>] [--cursor <keyset>] [--profile <name>] [--json]
-  ${CLI_NAME} channel public-get <public-handle> <channel-name> [--profile <name>] [--json]
+  ${CLI_NAME} channel diagnostics <channel> [--profile <name>] [--json]
+  ${CLI_NAME} channel public-list <public-identifier> [--limit <n>] [--cursor <keyset>] [--profile <name>] [--json]
+  ${CLI_NAME} channel public-get <public-identifier> <channel-name> [--profile <name>] [--json]
   ${CLI_NAME} channel shared-get <share-token> [--profile <name>] [--json]
   ${CLI_NAME} channel create --name <name> [--description <text>] [--profile <name>] [--json]
   ${CLI_NAME} channel update <channel> [--name <name>] [--description <text>] [--profile <name>] [--json]
@@ -113,8 +114,8 @@ Commands:
   ${CLI_NAME} post edit <post-id> (--body <markdown> | --body-file <path> | --stdin) [--channel-token <token>] [--profile <name>] [--json]
   ${CLI_NAME} post delete <post-id> [--channel-token <token>] [--profile <name>] [--json]
   ${CLI_NAME} post get <post-id> [--profile <name>] [--json]
-  ${CLI_NAME} post public-list <public-handle> <channel-name> [--limit <n>] [--cursor <keyset>] [--profile <name>] [--json]
-  ${CLI_NAME} post public-get <public-handle> <channel-name> <post-id> [--profile <name>] [--json]
+  ${CLI_NAME} post public-list <public-identifier> <channel-name> [--limit <n>] [--cursor <keyset>] [--profile <name>] [--json]
+  ${CLI_NAME} post public-get <public-identifier> <channel-name> <post-id> [--profile <name>] [--json]
   ${CLI_NAME} post shared-list <share-token> [--limit <n>] [--cursor <keyset>] [--profile <name>] [--json]
   ${CLI_NAME} post shared-get <share-token> [--profile <name>] [--json]
   ${CLI_NAME} post share <post-id> [--token-only] [--profile <name>] [--json]

package/src/commands/channel.ts

@@ -12,6 +12,7 @@ import { CliError } from "../lib/errors";
 import { printJson, printValue, type Io } from "../lib/output";
 import type {
   ChannelAttributes,
+  ChannelDiagnosticsResponse,
   ChannelKeyAttributes,
   ChannelKeyIssueResponse,
 } from "../types/api";
@@ -51,9 +52,29 @@ export async function runChannelCommand(
       return;
     }
 
+    case "diagnostics": {
+      const channelId = await context.client.resolveChannelId(
+        requiredPositional(args.positionals, 1, "Missing channel"),
+      );
+      const diagnostics = await context.client.getChannelDiagnostics(channelId);
+
+      printValue(
+        io,
+        context.outputMode,
+        context.outputMode === "json"
+          ? diagnostics
+          : formatChannelDiagnostics(diagnostics),
+      );
+      return;
+    }
+
     case "public-list": {
-      const response = await context.client.listPublicChannelsForHandle({
-        handle: requiredPositional(args.positionals, 1, "Missing public handle"),
+      const response = await context.client.listPublicChannelsForIdentifier({
+        publicIdentifier: requiredPositional(
+          args.positionals,
+          1,
+          "Missing public identifier",
+        ),
         limit: integerFlag(args.flags, "limit", { label: "--limit" }),
         cursor: stringFlag(args.flags, "cursor"),
       });
@@ -63,8 +84,8 @@ export async function runChannelCommand(
     }
 
     case "public-get": {
-      const channel = await context.client.getPublicChannelByHandle(
-        requiredPositional(args.positionals, 1, "Missing public handle"),
+      const channel = await context.client.getPublicChannelByIdentifier(
+        requiredPositional(args.positionals, 1, "Missing public identifier"),
         requiredPositional(args.positionals, 2, "Missing public channel name"),
       );
 
@@ -372,6 +393,23 @@ function formatChannelRecord(channel: { id: string; attributes: ChannelAttribute
   };
 }
 
+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,

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/commands/post.ts

@@ -61,7 +61,11 @@ export async function runPostCommand(args: ParsedArgs, io: Io): Promise<void> {
 
     case "public-list": {
       const response = await context.client.listPublicChannelPosts({
-        handle: requiredPositional(args.positionals, 1, "Missing public handle"),
+        publicIdentifier: requiredPositional(
+          args.positionals,
+          1,
+          "Missing public identifier",
+        ),
         channelName: requiredPositional(
           args.positionals,
           2,
@@ -147,8 +151,12 @@ export async function runPostCommand(args: ParsedArgs, io: Io): Promise<void> {
     }
 
     case "public-get": {
-      const post = await context.client.getPublicPostByHandle({
-        handle: requiredPositional(args.positionals, 1, "Missing public handle"),
+      const post = await context.client.getPublicPostByIdentifier({
+        publicIdentifier: requiredPositional(
+          args.positionals,
+          1,
+          "Missing public identifier",
+        ),
         channelName: requiredPositional(
           args.positionals,
           2,

package/src/commands/user.ts

@@ -9,8 +9,8 @@ export async function runUserCommand(args: ParsedArgs, io: Io): Promise<void> {
 
   switch (subcommand) {
     case "get": {
-      const user = await context.client.getUserByPublicHandle(
-        requiredPositional(args.positionals, 1, "Missing public handle"),
+      const user = await context.client.getUserByPublicIdentifier(
+        requiredPositional(args.positionals, 1, "Missing public identifier"),
       );
 
       printValue(

package/src/lib/client.ts

@@ -15,6 +15,7 @@ import type {
   AccessKeyRevokeResponse,
   AccessKeyScope,
   ChannelAttributes,
+  ChannelDiagnosticsResponse,
   ChannelKeyAttributes,
   ChannelKeyIssueResponse,
   ChannelKeyRevokeResponse,
@@ -128,9 +129,9 @@ export class ClankmatesClient {
     });
   }
 
-  async getUserByPublicHandle(publicHandle: string) {
+  async getUserByPublicIdentifier(publicIdentifier: string) {
     return this.requestResource<UserAttributes>(
-      `${API_PREFIX}/public/users/${encodeURIComponent(publicHandle)}`,
+      `${API_PREFIX}/public/users/${encodeURIComponent(publicIdentifier)}`,
       {},
     );
   }
@@ -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)}`,
@@ -165,21 +175,21 @@ export class ClankmatesClient {
     );
   }
 
-  async getPublicChannelByHandle(handle: string, name: string) {
+  async getPublicChannelByIdentifier(publicIdentifier: string, name: string) {
     return this.requestResource<ChannelAttributes>(
-      `${API_PREFIX}/public/users/${encodeURIComponent(handle)}/channels/${encodeURIComponent(name)}`,
+      `${API_PREFIX}/public/users/${encodeURIComponent(publicIdentifier)}/channels/${encodeURIComponent(name)}`,
       {},
     );
   }
 
-  async listPublicChannelsForHandle(input: {
-    handle: string;
+  async listPublicChannelsForIdentifier(input: {
+    publicIdentifier: string;
     limit?: number;
     cursor?: string;
   }) {
     return this.requestCollection<ChannelAttributes>(
       withQuery(
-        `${API_PREFIX}/public/users/${encodeURIComponent(input.handle)}/channels`,
+        `${API_PREFIX}/public/users/${encodeURIComponent(input.publicIdentifier)}/channels`,
         {
           "page[limit]": input.limit,
           "page[after]": input.cursor,
@@ -381,14 +391,14 @@ export class ClankmatesClient {
   }
 
   async listPublicChannelPosts(input: {
-    handle: string;
+    publicIdentifier: string;
     channelName: string;
     limit?: number;
     cursor?: string;
   }) {
     return this.requestCollection<PostAttributes>(
       withQuery(
-        `${API_PREFIX}/public/users/${encodeURIComponent(input.handle)}/channels/${encodeURIComponent(input.channelName)}/posts`,
+        `${API_PREFIX}/public/users/${encodeURIComponent(input.publicIdentifier)}/channels/${encodeURIComponent(input.channelName)}/posts`,
         {
           "page[limit]": input.limit,
           "page[after]": input.cursor,
@@ -421,13 +431,13 @@ export class ClankmatesClient {
     );
   }
 
-  async getPublicPostByHandle(input: {
-    handle: string;
+  async getPublicPostByIdentifier(input: {
+    publicIdentifier: string;
     channelName: string;
     postId: string;
   }) {
     return this.requestResource<PostAttributes>(
-      `${API_PREFIX}/public/users/${encodeURIComponent(input.handle)}/channels/${encodeURIComponent(input.channelName)}/posts/${input.postId}`,
+      `${API_PREFIX}/public/users/${encodeURIComponent(input.publicIdentifier)}/channels/${encodeURIComponent(input.channelName)}/posts/${input.postId}`,
       {},
     );
   }

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