@clankmates/cli 0.11.0 → 0.12.0

package/README.md

@@ -14,6 +14,7 @@ The current CLI supports:
 - post publish, edit, delete, share, and owner/public/shared reads
 - `My Feed` and feed search
 - inbox thread list/show, first-message sends, replies, and lifecycle actions
+- SQLite-backed local server timestamp cache for polling workflows
 - OpenAPI fetch, low-level API requests, diagnostics, and skill installation
 
 ## Install
@@ -46,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.0
+mise install npm:@clankmates/cli@0.12.0
 ```
 
 For local development in this repository:
@@ -99,10 +100,12 @@ 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 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
@@ -134,6 +137,14 @@ bun run cli -- inbox attachments <message-id> --json
 
 Paginated list commands accept `--limit <n>` and `--cursor <cursor>`. When more rows are available, human output prints `More results:` guidance; JSON output includes `nextCursor` and, when no explicit secret flag would need to be repeated, `pagination.nextCommand`.
 
+Polling-capable feed, post, and inbox reads accept `--since-cache` to reuse the locally stored server timestamp for that exact scope and `--save-cache` to persist the response timestamp after a successful request. Inspect or clear the SQLite timestamp cache with:
+
+```bash
+bun run cli -- cache status --json
+bun run cli -- cache clear --json
+bun run cli -- cache path
+```
+
 ## Useful Commands
 
 Inspect auth state:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clankmates/cli",
-  "version": "0.11.0",
+  "version": "0.12.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/cli.ts

@@ -14,6 +14,7 @@ import { runDoctorCommand } from "./commands/doctor";
 import { runSkillCommand } from "./commands/skill";
 import { runUserCommand } from "./commands/user";
 import { runSetupCommand } from "./commands/setup";
+import { runCacheCommand } from "./commands/cache";
 import { renderHelp, resolvesToHelpGroup } from "./lib/help";
 import { CLI_VERSION } from "./lib/version";
 
@@ -29,6 +30,7 @@ const COMMAND_HANDLERS = {
   skill: runSkillCommand,
   user: runUserCommand,
   setup: runSetupCommand,
+  cache: runCacheCommand,
 } as const;
 
 const CLI_NAME = "clankm";

package/src/commands/cache.ts

@@ -0,0 +1,124 @@
+import { stringFlag, type ParsedArgs } from "../lib/args";
+import {
+  openSyncCache,
+  type SyncScopeRow,
+} from "../lib/cache";
+import { createCommandContext } from "../lib/context";
+import { CliError } from "../lib/errors";
+import { formatTimestamp, renderFields } from "../lib/human";
+import { getCachePath } from "../lib/paths";
+import { printValue, type Io } from "../lib/output";
+
+export async function runCacheCommand(args: ParsedArgs, io: Io): Promise<void> {
+  const subcommand = args.positionals[0];
+
+  switch (subcommand) {
+    case "path": {
+      const cachePath = getCachePath();
+      printValue(
+        io,
+        args.flags.json === true ? "json" : "table",
+        args.flags.json === true ? { path: cachePath } : cachePath,
+      );
+      return;
+    }
+
+    case "status": {
+      const context = await createCommandContext(args, io);
+      const cache = await openSyncCache();
+
+      try {
+        const rows = cache.list({
+          baseUrl: context.profile.baseUrl,
+          profile: context.profileName,
+        });
+        printValue(
+          io,
+          context.outputMode,
+          context.outputMode === "json"
+            ? {
+                path: cache.path(),
+                profile: context.profileName,
+                baseUrl: context.profile.baseUrl,
+                scopes: rows.map(renderJsonScope),
+              }
+            : renderStatus(cache.path(), rows),
+        );
+      } finally {
+        cache.close();
+      }
+      return;
+    }
+
+    case "clear": {
+      const context = await createCommandContext(args, io);
+      const scope = stringFlag(args.flags, "scope");
+      const cache = await openSyncCache();
+
+      try {
+        const deleted = cache.clear(
+          scope
+            ? { scopeKey: scope }
+            : {
+                baseUrl: context.profile.baseUrl,
+                profile: context.profileName,
+              },
+        );
+        printValue(
+          io,
+          context.outputMode,
+          context.outputMode === "json"
+            ? { ok: true, deleted, scope: scope ?? null }
+            : `Cleared ${deleted} cache ${deleted === 1 ? "scope" : "scopes"}.`,
+        );
+      } finally {
+        cache.close();
+      }
+      return;
+    }
+
+    default:
+      throw new CliError("Unknown cache subcommand", 2);
+  }
+}
+
+function renderJsonScope(row: SyncScopeRow): Record<string, unknown> {
+  return {
+    scopeKey: row.scope_key,
+    baseUrl: row.base_url,
+    profile: row.profile,
+    actorKey: row.actor_key,
+    resource: row.resource,
+    params: JSON.parse(row.params_json),
+    serverTimestamp: row.server_timestamp,
+    cachedAt: row.cached_at,
+    cliVersion: row.cli_version,
+  };
+}
+
+function renderStatus(cachePath: string, rows: SyncScopeRow[]): string {
+  if (rows.length === 0) {
+    return renderFields([
+      ["Cache", cachePath],
+      ["Scopes", "0"],
+    ]);
+  }
+
+  const table = rows
+    .map((row) => ({
+      resource: row.resource,
+      scopeKey: row.scope_key,
+      serverTimestamp: formatTimestamp(row.server_timestamp),
+      cachedAt: formatTimestamp(row.cached_at),
+    }))
+    .map(
+      (row) =>
+        `${row.resource}\n  scope: ${row.scopeKey}\n  server timestamp: ${row.serverTimestamp}\n  cached: ${row.cachedAt}`,
+    )
+    .join("\n\n");
+
+  return `${renderFields([
+    ["Cache", cachePath],
+    ["Scopes", String(rows.length)],
+  ])}\n\n${table}`;
+}

package/src/commands/feed.ts

@@ -1,3 +1,17 @@
+import {
+  authenticatedActorKey,
+  assertSinceFlags,
+  cacheFlags,
+  cacheResult,
+  changeResponseMeta,
+  feedMyScope,
+  feedSearchScope,
+  prepareCachePlan,
+  saveCacheTimestamp,
+  type CachePlan,
+  type CacheResult,
+  type CacheScope,
+} from "../lib/cache";
 import {
   channelFlag,
   integerFlag,
@@ -18,15 +32,33 @@ export async function runFeedCommand(args: ParsedArgs, io: Io): Promise<void> {
   switch (subcommand) {
     case "my": {
       const context = await createCommandContext(args, io);
+      assertSinceFlags(args);
+      const channelId = await resolveChannelId(context, args);
+      const cacheScope = await maybeFeedMyScope(args, context, channelId);
+      const cachePlan = await maybePrepareCachePlan(args, context, cacheScope);
       const response = await context.client.myFeed({
-        channelId: await resolveChannelId(context, args),
+        channelId,
         limit: integerFlag(args.flags, "limit", { label: "--limit" }),
         cursor: stringFlag(args.flags, "cursor"),
+        before: stringFlag(args.flags, "before"),
         order: parseLatestFirstOrder(stringFlag(args.flags, "order")),
-        since: stringFlag(args.flags, "since"),
+        since: resolvedSince(args, cachePlan),
       });
+      const savedServerTimestamp = await maybeSaveCacheTimestamp(
+        args,
+        context,
+        cacheScope,
+        response.meta,
+        response.nextCursor === undefined,
+      );
 
-      printFeedResponse(args, context, io, response);
+      printFeedResponse(
+        args,
+        context,
+        io,
+        response,
+        cacheResult(cachePlan, savedServerTimestamp),
+      );
       return;
     }
 
@@ -37,27 +69,61 @@ export async function runFeedCommand(args: ParsedArgs, io: Io): Promise<void> {
         "Missing search query",
       );
       const context = await createCommandContext(args, io);
+      assertSinceFlags(args);
+      const channelId = await resolveChannelId(context, args);
+      const cacheScope = await maybeFeedSearchScope(args, context, query, channelId);
+      const cachePlan = await maybePrepareCachePlan(args, context, cacheScope);
       const response = await context.client.searchMyFeed({
         query,
-        channelId: await resolveChannelId(context, args),
+        channelId,
         limit: integerFlag(args.flags, "limit", { label: "--limit" }),
         cursor: stringFlag(args.flags, "cursor"),
+        before: stringFlag(args.flags, "before"),
         order: parseLatestFirstOrder(stringFlag(args.flags, "order")),
-        since: stringFlag(args.flags, "since"),
+        since: resolvedSince(args, cachePlan),
       });
+      const savedServerTimestamp = await maybeSaveCacheTimestamp(
+        args,
+        context,
+        cacheScope,
+        response.meta,
+        response.nextCursor === undefined,
+      );
 
-      printFeedResponse(args, context, io, response);
+      printFeedResponse(
+        args,
+        context,
+        io,
+        response,
+        cacheResult(cachePlan, savedServerTimestamp),
+      );
       return;
     }
 
     case "changes": {
       const context = await createCommandContext(args, io);
+      assertSinceFlags(args);
+      const channelId = await resolveChannelId(context, args);
+      const cacheScope = await maybeFeedMyScope(args, context, channelId);
+      const cachePlan = await maybePrepareCachePlan(args, context, cacheScope);
       const response = await context.client.checkMyFeedChanges({
-        since: requiredSince(args),
-        channelId: await resolveChannelId(context, args),
+        since: requiredSince(args, cachePlan),
+        channelId,
       });
+      const savedServerTimestamp = await maybeSaveCacheTimestamp(
+        args,
+        context,
+        cacheScope,
+        changeResponseMeta(response),
+        response.has_updates === false,
+      );
 
-      printChangeCheckResponse(context, io, response);
+      printChangeCheckResponse(
+        context,
+        io,
+        response,
+        cacheResult(cachePlan, savedServerTimestamp),
+      );
       return;
     }
 
@@ -83,6 +149,7 @@ function printFeedResponse(
     nextCursor?: string;
     meta?: Record<string, unknown>;
   },
+  cache?: CacheResult,
 ): void {
   if (context.outputMode === "json") {
     printJson(
@@ -91,6 +158,7 @@ function printFeedResponse(
         items: response.items,
         nextCursor: response.nextCursor,
         meta: response.meta,
+        ...(cache ? { cache } : {}),
       }),
     );
     return;
@@ -113,11 +181,28 @@ function printFeedResponse(
   if (message) {
     io.stdout(message);
   }
+
+  printCacheNote(io, cache);
 }
 
-function requiredSince(args: ParsedArgs): string {
+function requiredSince(args: ParsedArgs, cachePlan?: CachePlan): string {
   const since = stringFlag(args.flags, "since");
 
+  if (since) {
+    return since;
+  }
+
+  if (cachePlan?.previousServerTimestamp) {
+    return cachePlan.previousServerTimestamp;
+  }
+
+  if (cacheFlags(args).sinceCache) {
+    throw new CliError(
+      "No cached server timestamp for this feed scope. Run a read command with `--save-cache` first.",
+      2,
+    );
+  }
+
   if (!since) {
     throw new CliError("Missing `--since`", 2);
   }
@@ -141,12 +226,13 @@ function printChangeCheckResponse(
   context: CommandContext,
   io: Io,
   response: ChangeCheckResponse,
+  cache?: CacheResult,
 ): void {
   printValue(
     io,
     context.outputMode,
     context.outputMode === "json"
-      ? response
+      ? { ...response, ...(cache ? { cache } : {}) }
       : renderFields([
           ["Has updates", response.has_updates ? "yes" : "no"],
           ["Server time", formatTimestamp(response.server_time)],
@@ -156,6 +242,101 @@ function printChangeCheckResponse(
               ? undefined
               : `${response.recommended_poll_after_ms}ms`,
           ],
+          ...cacheFields(cache),
         ]),
   );
 }
+
+async function maybePrepareCachePlan(
+  args: ParsedArgs,
+  context: CommandContext,
+  scope: CacheScope | undefined,
+): Promise<CachePlan | undefined> {
+  return cacheFlags(args).sinceCache && scope
+    ? prepareCachePlan(context, scope)
+    : undefined;
+}
+
+async function maybeSaveCacheTimestamp(
+  args: ParsedArgs,
+  context: CommandContext,
+  scope: CacheScope | undefined,
+  meta: Record<string, unknown> | undefined,
+  shouldSave: boolean,
+): Promise<string | undefined> {
+  return cacheFlags(args).saveCache && scope && shouldSave
+    ? saveCacheTimestamp(context, scope, meta)
+    : undefined;
+}
+
+async function maybeFeedMyScope(
+  args: ParsedArgs,
+  context: CommandContext,
+  channelId?: string,
+): Promise<CacheScope | undefined> {
+  if (!cacheFlags(args).sinceCache && !cacheFlags(args).saveCache) {
+    return undefined;
+  }
+
+  return feedMyScope({
+    context,
+    actorKey: await authenticatedActorKey(context),
+    channelId,
+    before: stringFlag(args.flags, "before"),
+  });
+}
+
+async function maybeFeedSearchScope(
+  args: ParsedArgs,
+  context: CommandContext,
+  query: string,
+  channelId?: string,
+): Promise<CacheScope | undefined> {
+  if (!cacheFlags(args).sinceCache && !cacheFlags(args).saveCache) {
+    return undefined;
+  }
+
+  return feedSearchScope({
+    context,
+    actorKey: await authenticatedActorKey(context),
+    query,
+    channelId,
+    before: stringFlag(args.flags, "before"),
+  });
+}
+
+function resolvedSince(
+  args: ParsedArgs,
+  cachePlan: CachePlan | undefined,
+): string | undefined {
+  return stringFlag(args.flags, "since") ?? cachePlan?.previousServerTimestamp;
+}
+
+function printCacheNote(io: Io, cache: CacheResult | undefined): void {
+  if (!cache) {
+    return;
+  }
+
+  const details = [
+    cache.previousServerTimestamp
+      ? `used ${cache.previousServerTimestamp}`
+      : cache.hit
+        ? "used cache"
+        : "no cached timestamp",
+    cache.savedServerTimestamp ? `saved ${cache.savedServerTimestamp}` : undefined,
+  ].filter(Boolean);
+
+  io.stdout(`Cache: ${details.join("; ")}.`);
+}
+
+function cacheFields(cache: CacheResult | undefined): Array<[string, string | undefined]> {
+  if (!cache) {
+    return [];
+  }
+
+  return [
+    ["Cache scope", cache.scopeKey],
+    ["Cached timestamp", cache.previousServerTimestamp],
+    ["Saved timestamp", cache.savedServerTimestamp],
+  ];
+}