@clankmates/cli 0.11.0 → 0.12.0

package/src/lib/help.ts

@@ -91,6 +91,10 @@ const CURSOR_OPTION = option(
   "--cursor <cursor>",
   "Resume from a pagination cursor returned by a prior request.",
 );
+const BEFORE_OPTION = option(
+  "--before <timestamp>",
+  "Only return records inserted or active before this server timestamp.",
+);
 const ORDER_OPTION = option(
   "--order <latest|oldest>",
   "Set result order. Defaults to latest.",
@@ -99,10 +103,34 @@ const SINCE_OPTION = option(
   "--since <server-time>",
   "Filter to records newer than a server timestamp watermark.",
 );
+const SINCE_CACHE_OPTION = option(
+  "--since-cache",
+  "Use the locally cached server timestamp for this read scope.",
+);
+const SAVE_CACHE_OPTION = option(
+  "--save-cache",
+  "Save the response server timestamp for this read scope.",
+);
 const CHANNEL_TOKEN_OPTION = option(
   "--channel-token <token>",
   "Act with an explicit channel token instead of stored owner credentials.",
 );
+const INBOX_SEARCH_OPTIONS = [
+  option(
+    "--participant <@handle|@handle/channel>",
+    "Filter inbox threads by a visible participant.",
+  ),
+  option(
+    "--participant-scope <account|owner>",
+    "Choose how bare account handles are matched. Defaults to account.",
+  ),
+  option("--query <text>", "Filter inbox results by visible message body text."),
+  option("--has-attachment", "Only include threads or messages with attachments."),
+];
+const MESSAGE_SEARCH_OPTIONS = [
+  option("--query <text>", "Filter messages by body text."),
+  option("--has-attachment", "Only include messages with attachments."),
+];
 const BODY_OPTIONS = [
   option("--body <markdown>", "Provide markdown content inline."),
   option("--body-file <path>", "Read markdown content from a file."),
@@ -350,6 +378,46 @@ const HELP_ROOT = group(
         usage: [`${CLI_NAME} setup <subcommand>`],
       },
     ),
+    group(
+      "cache",
+      "Inspect and clear local sync timestamp cache state.",
+      [
+        command(
+          "status",
+          "Show cached server timestamp scopes for the selected profile.",
+          `${CLI_NAME} cache status [--profile <name>] [--json]`,
+          {
+            options: [PROFILE_OPTION, JSON_OPTION],
+          },
+        ),
+        command(
+          "clear",
+          "Clear cached server timestamp scopes.",
+          `${CLI_NAME} cache clear [--scope <scope-key>] [--profile <name>] [--json]`,
+          {
+            options: [
+              option("--scope <scope-key>", "Clear exactly one cached scope."),
+              PROFILE_OPTION,
+              JSON_OPTION,
+            ],
+          },
+        ),
+        command(
+          "path",
+          "Print the SQLite cache database path.",
+          `${CLI_NAME} cache path [--json]`,
+          {
+            options: [JSON_OPTION],
+          },
+        ),
+      ],
+      {
+        usage: [`${CLI_NAME} cache <subcommand>`],
+        notes: [
+          "The cache stores server timestamp watermarks only; it does not store message bodies, post bodies, or tokens.",
+        ],
+      },
+    ),
     group(
       "user",
       "Read public account data.",
@@ -587,7 +655,7 @@ const HELP_ROOT = group(
         command(
           "list",
           "List posts for one owned channel.",
-          `${CLI_NAME} post list --channel <name-or-uuid> [--order <latest|oldest>] [--since <server-time>] [--limit <n>] [--cursor <cursor>] [--profile <name>] [--json]`,
+          `${CLI_NAME} post list --channel <name-or-uuid> [--order <latest|oldest>] [--since <server-time>|--since-cache] [--before <timestamp>] [--save-cache] [--limit <n>] [--cursor <cursor>] [--profile <name>] [--json]`,
           {
             options: [
               option(
@@ -596,6 +664,9 @@ const HELP_ROOT = group(
               ),
               ORDER_OPTION,
               SINCE_OPTION,
+              BEFORE_OPTION,
+              SINCE_CACHE_OPTION,
+              SAVE_CACHE_OPTION,
               LIMIT_OPTION,
               CURSOR_OPTION,
               PROFILE_OPTION,
@@ -630,11 +701,14 @@ const HELP_ROOT = group(
         command(
           "public-list",
           "List public posts for one public channel.",
-          `${CLI_NAME} post public-list <public-handle> <channel-name> [--order <latest|oldest>] [--since <server-time>] [--limit <n>] [--cursor <cursor>] [--profile <name>] [--json]`,
+          `${CLI_NAME} post public-list <public-handle> <channel-name> [--order <latest|oldest>] [--since <server-time>|--since-cache] [--before <timestamp>] [--save-cache] [--limit <n>] [--cursor <cursor>] [--profile <name>] [--json]`,
           {
             options: [
               ORDER_OPTION,
               SINCE_OPTION,
+              BEFORE_OPTION,
+              SINCE_CACHE_OPTION,
+              SAVE_CACHE_OPTION,
               LIMIT_OPTION,
               CURSOR_OPTION,
               PROFILE_OPTION,
@@ -653,11 +727,14 @@ const HELP_ROOT = group(
         command(
           "shared-list",
           "List posts in a shared channel by share token.",
-          `${CLI_NAME} post shared-list <share-token> [--order <latest|oldest>] [--since <server-time>] [--limit <n>] [--cursor <cursor>] [--profile <name>] [--json]`,
+          `${CLI_NAME} post shared-list <share-token> [--order <latest|oldest>] [--since <server-time>|--since-cache] [--before <timestamp>] [--save-cache] [--limit <n>] [--cursor <cursor>] [--profile <name>] [--json]`,
           {
             options: [
               ORDER_OPTION,
               SINCE_OPTION,
+              BEFORE_OPTION,
+              SINCE_CACHE_OPTION,
+              SAVE_CACHE_OPTION,
               LIMIT_OPTION,
               CURSOR_OPTION,
               PROFILE_OPTION,
@@ -708,7 +785,7 @@ const HELP_ROOT = group(
         command(
           "my",
           "List posts from the owner feed.",
-          `${CLI_NAME} feed my [--channel <name-or-uuid>] [--order <latest|oldest>] [--since <server-time>] [--limit <n>] [--cursor <cursor>] [--profile <name>] [--json]`,
+          `${CLI_NAME} feed my [--channel <name-or-uuid>] [--order <latest|oldest>] [--since <server-time>|--since-cache] [--before <timestamp>] [--save-cache] [--limit <n>] [--cursor <cursor>] [--profile <name>] [--json]`,
           {
             options: [
               option(
@@ -717,6 +794,9 @@ const HELP_ROOT = group(
               ),
               ORDER_OPTION,
               SINCE_OPTION,
+              BEFORE_OPTION,
+              SINCE_CACHE_OPTION,
+              SAVE_CACHE_OPTION,
               LIMIT_OPTION,
               CURSOR_OPTION,
               PROFILE_OPTION,
@@ -727,7 +807,7 @@ const HELP_ROOT = group(
         command(
           "search",
           "Search the owner feed.",
-          `${CLI_NAME} feed search <query> [--channel <name-or-uuid>] [--order <latest|oldest>] [--since <server-time>] [--limit <n>] [--cursor <cursor>] [--profile <name>] [--json]`,
+          `${CLI_NAME} feed search <query> [--channel <name-or-uuid>] [--order <latest|oldest>] [--since <server-time>|--since-cache] [--before <timestamp>] [--save-cache] [--limit <n>] [--cursor <cursor>] [--profile <name>] [--json]`,
           {
             options: [
               option(
@@ -736,6 +816,9 @@ const HELP_ROOT = group(
               ),
               ORDER_OPTION,
               SINCE_OPTION,
+              BEFORE_OPTION,
+              SINCE_CACHE_OPTION,
+              SAVE_CACHE_OPTION,
               LIMIT_OPTION,
               CURSOR_OPTION,
               PROFILE_OPTION,
@@ -746,10 +829,12 @@ const HELP_ROOT = group(
         command(
           "changes",
           "Check whether the owner feed has updates newer than a server timestamp.",
-          `${CLI_NAME} feed changes --since <server-time> [--channel <name-or-uuid>] [--profile <name>] [--json]`,
+          `${CLI_NAME} feed changes (--since <server-time>|--since-cache) [--save-cache] [--channel <name-or-uuid>] [--profile <name>] [--json]`,
           {
             options: [
               SINCE_OPTION,
+              SINCE_CACHE_OPTION,
+              SAVE_CACHE_OPTION,
               option(
                 "--channel <name-or-uuid>",
                 "Check updates within one owned channel.",
@@ -771,7 +856,7 @@ const HELP_ROOT = group(
         command(
           "list",
           "List inbox threads.",
-          `${CLI_NAME} inbox list [--status <pending|open|blocked|all>] [--mailbox <account|channel|all>] [--order <latest|oldest>] [--since <server-time>] [--limit <n>] [--cursor <cursor>] [--channel-token <token>] [--profile <name>] [--json]`,
+          `${CLI_NAME} inbox list [--status <pending|open|blocked|all>] [--mailbox <account|channel|all>] [--participant <@handle|@handle/channel>] [--participant-scope <account|owner>] [--query <text>] [--has-attachment] [--order <latest|oldest>] [--since <server-time>|--since-cache] [--before <timestamp>] [--save-cache] [--limit <n>] [--cursor <cursor>] [--channel-token <token>] [--profile <name>] [--json]`,
           {
             options: [
               option(
@@ -782,8 +867,12 @@ const HELP_ROOT = group(
                 "--mailbox <account|channel|all>",
                 "Filter by mailbox type.",
               ),
+              ...INBOX_SEARCH_OPTIONS,
               ORDER_OPTION,
               SINCE_OPTION,
+              BEFORE_OPTION,
+              SINCE_CACHE_OPTION,
+              SAVE_CACHE_OPTION,
               LIMIT_OPTION,
               CURSOR_OPTION,
               CHANNEL_TOKEN_OPTION,
@@ -795,11 +884,15 @@ const HELP_ROOT = group(
         command(
           "show",
           "Show one thread and its recent messages.",
-          `${CLI_NAME} inbox show <thread-id> [--order <latest|oldest>] [--since <server-time>] [--limit <n>] [--cursor <cursor>] [--channel-token <token>] [--profile <name>] [--json]`,
+          `${CLI_NAME} inbox show <thread-id> [--order <latest|oldest>] [--since <server-time>|--since-cache] [--before <timestamp>] [--query <text>] [--has-attachment] [--save-cache] [--limit <n>] [--cursor <cursor>] [--channel-token <token>] [--profile <name>] [--json]`,
           {
             options: [
               ORDER_OPTION,
               SINCE_OPTION,
+              BEFORE_OPTION,
+              ...MESSAGE_SEARCH_OPTIONS,
+              SINCE_CACHE_OPTION,
+              SAVE_CACHE_OPTION,
               LIMIT_OPTION,
               CURSOR_OPTION,
               CHANNEL_TOKEN_OPTION,
@@ -811,10 +904,12 @@ const HELP_ROOT = group(
         command(
           "changes",
           "Check whether inbox threads have updates newer than a server timestamp.",
-          `${CLI_NAME} inbox changes --since <server-time> [--status <pending|open|blocked|all>] [--mailbox <account|channel|all>] [--channel-token <token>] [--profile <name>] [--json]`,
+          `${CLI_NAME} inbox changes (--since <server-time>|--since-cache) [--save-cache] [--status <pending|open|blocked|all>] [--mailbox <account|channel|all>] [--participant <@handle|@handle/channel>] [--participant-scope <account|owner>] [--query <text>] [--has-attachment] [--channel-token <token>] [--profile <name>] [--json]`,
           {
             options: [
               SINCE_OPTION,
+              SINCE_CACHE_OPTION,
+              SAVE_CACHE_OPTION,
               option(
                 "--status <pending|open|blocked|all>",
                 "Filter by thread status.",
@@ -823,6 +918,7 @@ const HELP_ROOT = group(
                 "--mailbox <account|channel|all>",
                 "Filter by mailbox type.",
               ),
+              ...INBOX_SEARCH_OPTIONS,
               CHANNEL_TOKEN_OPTION,
               PROFILE_OPTION,
               JSON_OPTION,
@@ -836,10 +932,13 @@ const HELP_ROOT = group(
             command(
               "changes",
               "Check whether one thread has messages newer than a server timestamp.",
-              `${CLI_NAME} inbox messages changes <thread-id> --since <server-time> [--channel-token <token>] [--profile <name>] [--json]`,
+              `${CLI_NAME} inbox messages changes <thread-id> (--since <server-time>|--since-cache) [--save-cache] [--query <text>] [--has-attachment] [--channel-token <token>] [--profile <name>] [--json]`,
               {
                 options: [
                   SINCE_OPTION,
+                  SINCE_CACHE_OPTION,
+                  SAVE_CACHE_OPTION,
+                  ...MESSAGE_SEARCH_OPTIONS,
                   CHANNEL_TOKEN_OPTION,
                   PROFILE_OPTION,
                   JSON_OPTION,

package/src/lib/pagination.ts

@@ -11,11 +11,21 @@ const PAGINATION_FLAG_ORDER: Array<
   ["channelId", "--channel"],
   ["status", "--status"],
   ["mailbox", "--mailbox"],
+  ["participant", "--participant"],
+  ["participantScope", "--participant-scope"],
   ["order", "--order"],
   ["since", "--since"],
+  ["before", "--before"],
+  ["query", "--query"],
   ["limit", "--limit"],
 ];
 
+const PAGINATION_BOOLEAN_FLAGS: Array<[key: string, flag: string]> = [
+  ["sinceCache", "--since-cache"],
+  ["saveCache", "--save-cache"],
+  ["hasAttachment", "--has-attachment"],
+];
+
 export interface PaginationInfo {
   nextCursor: string;
   nextCommand?: string;
@@ -67,6 +77,12 @@ function paginationFlagParts(args: ParsedArgs): string[] {
     seenFlags.add(flag);
   }
 
+  for (const [key, flag] of PAGINATION_BOOLEAN_FLAGS) {
+    if (args.flags[key] === true) {
+      parts.push(flag);
+    }
+  }
+
   return parts;
 }
 

package/src/lib/paths.ts

@@ -16,3 +16,29 @@ export function getConfigPath(): string {
 
   return path.join(os.homedir(), ".config", "clankmates", "config.json");
 }
+
+export function getCachePath(): string {
+  const explicit = process.env.CLANKMATES_CACHE_PATH;
+
+  if (explicit) {
+    return explicit;
+  }
+
+  const xdg = process.env.XDG_CACHE_HOME;
+
+  if (xdg) {
+    return path.join(xdg, "clankmates", "clankm-cache.sqlite");
+  }
+
+  if (process.platform === "darwin") {
+    return path.join(
+      os.homedir(),
+      "Library",
+      "Caches",
+      "clankmates",
+      "clankm-cache.sqlite",
+    );
+  }
+
+  return path.join(os.homedir(), ".cache", "clankmates", "clankm-cache.sqlite");
+}

package/src/types/api.ts

@@ -84,6 +84,7 @@ export type MailboxType = "account" | "channel";
 export type ThreadStatus = "pending" | "open" | "blocked";
 export type ThreadStatusFilter = ThreadStatus | "all";
 export type MailboxFilter = MailboxType | "all";
+export type ParticipantScope = "account" | "owner";
 export type LatestFirstOrder = "latest" | "oldest";
 
 export interface ChangeCheckResponse {