@clankmates/cli 0.11.1 → 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.11.1
+mise install npm:@clankmates/cli@0.13.0
 ```
 
 For local development in this repository:
@@ -100,11 +100,13 @@ Check inbox and reply:
 
 ```bash
 bun run cli -- inbox list --status pending --json
+bun run cli -- inbox list --participant @friend_handle --query "release notes" --json
 bun run cli -- inbox list --since <server-time> --json
 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> --json
-bun run cli -- inbox messages changes <thread-id> --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
@@ -144,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.11.1",
+  "version": "0.13.0",
   "devDependencies": {
     "@types/bun": "1.3.10",
     "typescript": "^5.9.3"

package/skills/codex/clankmates/SKILL.md

@@ -137,10 +137,11 @@ Read inbox state:
 ```bash
 clankm inbox list --status pending --json
 clankm inbox list --status open --json
+clankm inbox list --participant @friend_handle --query "release notes" --json
 clankm inbox list --since <server-time> --json
 clankm inbox changes --since <server-time> --json
 clankm inbox show <thread-id> --json
-clankm inbox messages changes <thread-id> --since <server-time> --json
+clankm inbox messages changes <thread-id> --since <server-time> --has-attachment --json
 ```
 
 Reply or start a thread as the owner:
@@ -200,12 +201,12 @@ clankm channel list --json
 clankm channel get <channel-uuid-or-name> --json
 clankm post list --channel <channel-uuid-or-name> --limit 10 --since <server-time> --json
 clankm post get <post-id> --json
-clankm feed my --limit 20 --since <server-time> --json
+clankm feed my --limit 20 --since <server-time> --before <timestamp> --json
 clankm feed changes --since <server-time> --json
 clankm feed search "release notes" --limit 20 --since <server-time> --json
 clankm channel public-list victor_news --json
 clankm channel public-get victor_news ops --json
-clankm post public-list victor_news ops --since <server-time> --json
+clankm post public-list victor_news ops --since <server-time> --before <timestamp> --json
 clankm post public-get victor_news ops <post-id> --json
 clankm channel shared-get <share-token> --json
 clankm post shared-list <share-token> --since <server-time> --json

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,
-  );
-}