@clankmates/cli 0.12.0 → 0.13.0

package/README.md

@@ -47,7 +47,7 @@ MISE_FETCH_REMOTE_VERSIONS_CACHE=0 mise upgrade npm:@clankmates/cli
 You can also pin an exact release:
 
 ```bash
-mise install npm:@clankmates/cli@0.12.0
+mise install npm:@clankmates/cli@0.13.0
 ```
 
 For local development in this repository:
@@ -106,6 +106,7 @@ bun run cli -- inbox list --since-cache --save-cache --json
 bun run cli -- inbox changes --since <server-time> --json
 bun run cli -- inbox show <thread-id> --before <timestamp> --json
 bun run cli -- inbox messages changes <thread-id> --since <server-time> --has-attachment --json
+bun run cli -- inbox watch messages <thread-id> --once
 bun run cli -- inbox send @friend_handle --body-file ./intro.md --json
 bun run cli -- inbox send @victor_news/ops --body-file ./intro.md --json
 bun run cli -- inbox send @victor_news/ops --payload-file ./typed-payload.json --json
@@ -145,6 +146,8 @@ bun run cli -- cache clear --json
 bun run cli -- cache path
 ```
 
+Watch commands are JSONL-only streams for agents and scripts. `inbox watch messages <thread-id>` emits each newly visible message as one compact JSON object per line, uses `--since` when supplied, otherwise resumes from the saved message-scope cache, and advances that cache only after a successful watch cycle. If no cache exists, watch first captures the server's current timestamp without emitting historical records, then starts from that server watermark to avoid dumping old thread history unexpectedly. Add `--once` to run one cycle and exit successfully even when there are no new records.
+
 ## Useful Commands
 
 Inspect auth state:

package/package.json

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

package/src/commands/auth/access-keys.ts

@@ -0,0 +1,206 @@
+import {
+  booleanFlag,
+  requiredPositional,
+  requiredStringFlag,
+  stringFlag,
+  type ParsedArgs,
+} from "../../lib/args";
+import { resolveOutputMode } from "../../lib/context";
+import { loadConfig, resolveProfile, updateProfile } from "../../lib/config";
+import { ClankmatesClient } from "../../lib/client";
+import { CliError } from "../../lib/errors";
+import { joinBlocks, renderFields, renderTokenAction } from "../../lib/human";
+import { printJson, printValue, type Io } from "../../lib/output";
+import { getConfigPath } from "../../lib/paths";
+import type {
+  AccessKeyAttributes,
+  AccessKeyIssueResponse,
+  AccessKeyRevokeResponse,
+  AccessKeyScope,
+  ProfileConfig,
+} from "../../types/api";
+
+export async function runAccessKeyCommand(
+  args: ParsedArgs,
+  config: Awaited<ReturnType<typeof loadConfig>>,
+  io: Io,
+): Promise<void> {
+  const keyCommand = requiredPositional(
+    args.positionals,
+    1,
+    "Missing auth key subcommand",
+  );
+  const { profileName, profile } = resolveProfile(
+    config,
+    stringFlag(args.flags, "profile"),
+    stringFlag(args.flags, "baseUrl"),
+  );
+  const outputMode = resolveOutputMode(profile, args.flags);
+  const client = new ClankmatesClient(profile);
+  const configPath = getConfigPath();
+
+  switch (keyCommand) {
+    case "list": {
+      const scope = parseAccessKeyScope(stringFlag(args.flags, "scope"), false);
+      const response = await client.listAccessKeys(scope);
+
+      if (outputMode === "json") {
+        printJson(io, { items: response.items });
+        return;
+      }
+
+      printValue(
+        io,
+        outputMode,
+        response.items.map((item) => formatAccessKeyRow(item)),
+      );
+      return;
+    }
+
+    case "issue": {
+      const scope = requireAccessKeyScope(
+        requiredStringFlag(args.flags, "scope"),
+      );
+      const response = await client.issueAccessKey({
+        scope,
+        name: requiredStringFlag(args.flags, "name"),
+      });
+
+      if (booleanFlag(args.flags, "tokenOnly")) {
+        io.stdout(response.token);
+        return;
+      }
+
+      printValue(
+        io,
+        outputMode,
+        outputMode === "json"
+          ? response
+          : renderAccessKeyIssue("Issued owner access key", response),
+      );
+      return;
+    }
+
+    case "revoke": {
+      const response = await client.revokeAccessKey(
+        requiredPositional(args.positionals, 2, "Missing access key id"),
+      );
+      await pruneInvalidStoredOwnerTokens(
+        profileName,
+        profile,
+        client,
+        configPath,
+      );
+      printValue(
+        io,
+        outputMode,
+        outputMode === "json"
+          ? response
+          : renderAccessKeyRevoke("Revoked owner access key", response),
+      );
+      return;
+    }
+
+    default:
+      throw new CliError("Unknown auth key subcommand", 2);
+  }
+}
+
+function parseAccessKeyScope(
+  scope: string | undefined,
+  required: boolean,
+): AccessKeyScope | undefined {
+  if (scope === undefined) {
+    if (required) {
+      throw new CliError("Missing `--scope`", 2);
+    }
+
+    return undefined;
+  }
+
+  if (scope !== "master" && scope !== "read_only") {
+    throw new CliError("`--scope` must be either `master` or `read_only`.", 2);
+  }
+
+  return scope;
+}
+
+function requireAccessKeyScope(scope: string): AccessKeyScope {
+  const parsed = parseAccessKeyScope(scope, true);
+
+  if (!parsed) {
+    throw new CliError("Missing `--scope`", 2);
+  }
+
+  return parsed;
+}
+
+function formatAccessKeyRow(item: { id: string; attributes: AccessKeyAttributes }) {
+  return {
+    id: item.id,
+    scope: item.attributes.scope,
+    name: item.attributes.name ?? "",
+    expiresAt: item.attributes.expires_at,
+    issuedAt: item.attributes.inserted_at ?? "",
+  };
+}
+
+function renderAccessKeyIssue(
+  title: string,
+  response: AccessKeyIssueResponse,
+): string {
+  return renderTokenAction({
+    title,
+    id: response.id,
+    name: response.name,
+    token: response.token,
+    issuedAt: response.issued_at,
+    expiresAt: response.expires_at,
+  });
+}
+
+function renderAccessKeyRevoke(
+  title: string,
+  response: AccessKeyRevokeResponse,
+): string {
+  return joinBlocks([
+    title,
+    renderFields([
+      ["ID", response.id],
+      ["Scope", response.scope],
+      ["Name", response.name],
+    ]),
+  ]);
+}
+
+async function pruneInvalidStoredOwnerTokens(
+  profileName: string,
+  profile: ProfileConfig,
+  client: ClankmatesClient,
+  configPath: string,
+): Promise<void> {
+  const invalidMasterToken = profile.masterToken
+    ? !(await client.canAuthenticate(profile.masterToken))
+    : false;
+  const invalidReadOnlyToken = profile.readOnlyToken
+    ? !(await client.canAuthenticate(profile.readOnlyToken))
+    : false;
+
+  if (!invalidMasterToken && !invalidReadOnlyToken) {
+    return;
+  }
+
+  await updateProfile(
+    profileName,
+    (storedProfile) => {
+      if (invalidMasterToken) {
+        storedProfile.masterToken = undefined;
+      }
+
+      if (invalidReadOnlyToken) {
+        storedProfile.readOnlyToken = undefined;
+      }
+    },
+    configPath,
+  );
+}

package/src/commands/auth.ts

@@ -2,7 +2,6 @@ import { resolveOutputMode } from "../lib/context";
 import {
   booleanFlag,
   requiredPositional,
-  requiredStringFlag,
   stringFlag,
   type ParsedArgs,
 } from "../lib/args";
@@ -15,22 +14,15 @@ import {
 } from "../lib/config";
 import { ClankmatesClient } from "../lib/client";
 import { CliError } from "../lib/errors";
-import { joinBlocks, renderFields, renderTokenAction } from "../lib/human";
-import { printJson, printValue, type Io } from "../lib/output";
+import { printValue, type Io } from "../lib/output";
 import { getConfigPath } from "../lib/paths";
 import {
   resolveMasterToken,
   resolveOwnerReadToken,
   resolveReadOnlyToken,
 } from "../lib/tokens";
-import type {
-  AccessKeyAttributes,
-  AccessKeyIssueResponse,
-  AccessKeyRevokeResponse,
-  AccessKeyScope,
-  ProfileConfig,
-  WhoamiResponse,
-} from "../types/api";
+import type { ProfileConfig, WhoamiResponse } from "../types/api";
+import { runAccessKeyCommand } from "./auth/access-keys";
 
 export async function runAuthCommand(args: ParsedArgs, io: Io): Promise<void> {
   const subcommand = args.positionals[0];
@@ -196,92 +188,6 @@ export async function runAuthCommand(args: ParsedArgs, io: Io): Promise<void> {
   }
 }
 
-async function runAccessKeyCommand(
-  args: ParsedArgs,
-  config: Awaited<ReturnType<typeof loadConfig>>,
-  io: Io,
-): Promise<void> {
-  const keyCommand = requiredPositional(
-    args.positionals,
-    1,
-    "Missing auth key subcommand",
-  );
-  const { profileName, profile } = resolveProfile(
-    config,
-    stringFlag(args.flags, "profile"),
-    stringFlag(args.flags, "baseUrl"),
-  );
-  const outputMode = resolveOutputMode(profile, args.flags);
-  const client = new ClankmatesClient(profile);
-  const configPath = getConfigPath();
-
-  switch (keyCommand) {
-    case "list": {
-      const scope = parseAccessKeyScope(stringFlag(args.flags, "scope"), false);
-      const response = await client.listAccessKeys(scope);
-
-      if (outputMode === "json") {
-        printJson(io, { items: response.items });
-        return;
-      }
-
-      printValue(
-        io,
-        outputMode,
-        response.items.map((item) => formatAccessKeyRow(item)),
-      );
-      return;
-    }
-
-    case "issue": {
-      const scope = requireAccessKeyScope(
-        requiredStringFlag(args.flags, "scope"),
-      );
-      const response = await client.issueAccessKey({
-        scope,
-        name: requiredStringFlag(args.flags, "name"),
-      });
-
-      if (booleanFlag(args.flags, "tokenOnly")) {
-        io.stdout(response.token);
-        return;
-      }
-
-      printValue(
-        io,
-        outputMode,
-        outputMode === "json"
-          ? response
-          : renderAccessKeyIssue("Issued owner access key", response),
-      );
-      return;
-    }
-
-    case "revoke": {
-      const response = await client.revokeAccessKey(
-        requiredPositional(args.positionals, 2, "Missing access key id"),
-      );
-      await pruneInvalidStoredOwnerTokens(
-        profileName,
-        profile,
-        client,
-        configPath,
-      );
-      printValue(
-        io,
-        outputMode,
-        outputMode === "json"
-          ? response
-          : renderAccessKeyRevoke("Revoked owner access key", response),
-      );
-      return;
-    }
-
-    default:
-      throw new CliError("Unknown auth key subcommand", 2);
-  }
-}
-
 function defaultProfileConfig(): ProfileConfig {
   return {
     baseUrl: resolveBaseUrl(),
@@ -332,102 +238,3 @@ function formatWhoamiOutput(
     publicUrl: whoami.actor.public_url ?? "",
   };
 }
-
-function parseAccessKeyScope(
-  scope: string | undefined,
-  required: boolean,
-): AccessKeyScope | undefined {
-  if (scope === undefined) {
-    if (required) {
-      throw new CliError("Missing `--scope`", 2);
-    }
-
-    return undefined;
-  }
-
-  if (scope !== "master" && scope !== "read_only") {
-    throw new CliError("`--scope` must be either `master` or `read_only`.", 2);
-  }
-
-  return scope;
-}
-
-function requireAccessKeyScope(scope: string): AccessKeyScope {
-  const parsed = parseAccessKeyScope(scope, true);
-
-  if (!parsed) {
-    throw new CliError("Missing `--scope`", 2);
-  }
-
-  return parsed;
-}
-
-function formatAccessKeyRow(item: { id: string; attributes: AccessKeyAttributes }) {
-  return {
-    id: item.id,
-    scope: item.attributes.scope,
-    name: item.attributes.name ?? "",
-    expiresAt: item.attributes.expires_at,
-    issuedAt: item.attributes.inserted_at ?? "",
-  };
-}
-
-function renderAccessKeyIssue(
-  title: string,
-  response: AccessKeyIssueResponse,
-): string {
-  return renderTokenAction({
-    title,
-    id: response.id,
-    name: response.name,
-    token: response.token,
-    issuedAt: response.issued_at,
-    expiresAt: response.expires_at,
-  });
-}
-
-function renderAccessKeyRevoke(
-  title: string,
-  response: AccessKeyRevokeResponse,
-): string {
-  return joinBlocks([
-    title,
-    renderFields([
-      ["ID", response.id],
-      ["Scope", response.scope],
-      ["Name", response.name],
-    ]),
-  ]);
-}
-
-async function pruneInvalidStoredOwnerTokens(
-  profileName: string,
-  profile: ProfileConfig,
-  client: ClankmatesClient,
-  configPath: string,
-): Promise<void> {
-  const invalidMasterToken = profile.masterToken
-    ? !(await client.canAuthenticate(profile.masterToken))
-    : false;
-  const invalidReadOnlyToken = profile.readOnlyToken
-    ? !(await client.canAuthenticate(profile.readOnlyToken))
-    : false;
-
-  if (!invalidMasterToken && !invalidReadOnlyToken) {
-    return;
-  }
-
-  await updateProfile(
-    profileName,
-    (storedProfile) => {
-      if (invalidMasterToken) {
-        storedProfile.masterToken = undefined;
-      }
-
-      if (invalidReadOnlyToken) {
-        storedProfile.readOnlyToken = undefined;
-      }
-    },
-    configPath,
-  );
-}

package/src/commands/channel/render.ts

@@ -0,0 +1,224 @@
+import {
+  joinBlocks,
+  renderFields,
+  renderPagination,
+  renderTokenAction,
+} from "../../lib/human";
+import { printJson, printValue, type Io } from "../../lib/output";
+import { paginatedJson, paginationInfo } from "../../lib/pagination";
+import type { ParsedArgs } from "../../lib/args";
+import type {
+  ChannelAttributes,
+  ChannelDiagnosticsResponse,
+  ChannelKeyAttributes,
+  ChannelKeyIssueResponse,
+  ChannelKeyRevokeResponse,
+  ChannelPinResponse,
+  ChannelPublicationResponse,
+  IdResponse,
+  ShareTokenResponse,
+} from "../../types/api";
+
+export 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);
+  }
+}
+
+export function printChannelKeyCollection(
+  args: ParsedArgs,
+  outputMode: "json" | "table",
+  io: Io,
+  response: {
+    items: Array<{ id: string; attributes: ChannelKeyAttributes }>;
+    nextCursor?: string;
+  },
+): void {
+  if (outputMode === "json") {
+    printJson(
+      io,
+      paginatedJson(args, {
+        items: response.items,
+        nextCursor: response.nextCursor,
+      }),
+    );
+    return;
+  }
+
+  printValue(
+    io,
+    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);
+  }
+}
+
+export 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 ?? "",
+  };
+}
+
+export 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 ??
+      "",
+  };
+}
+
+export function renderShareToken(
+  title: string,
+  response: ShareTokenResponse,
+): string {
+  return joinBlocks([
+    title,
+    renderFields([["Token", response.token]]),
+  ]);
+}
+
+export function renderIdAction(title: string, response: IdResponse): string {
+  return joinBlocks([
+    title,
+    renderFields([["ID", response.id]]),
+  ]);
+}
+
+export function renderChannelPublicationAction(
+  title: string,
+  response: ChannelPublicationResponse,
+): string {
+  return joinBlocks([
+    title,
+    renderFields([
+      ["ID", response.id],
+      ["Name", response.name],
+      ["Publicly listed", response.publicly_listed],
+    ]),
+  ]);
+}
+
+export 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 ?? ""],
+    ]),
+  ]);
+}
+
+export 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,
+  });
+}
+
+export function renderChannelKeyRevoke(
+  title: string,
+  response: ChannelKeyRevokeResponse,
+): string {
+  return joinBlocks([
+    title,
+    renderFields([
+      ["ID", response.id],
+      ["Name", response.name],
+    ]),
+  ]);
+}
+
+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 ?? "",
+  };
+}