@clankmates/cli 0.10.3 → 0.11.1

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.10.3
+mise install npm:@clankmates/cli@0.11.1
 ```
 
 For local development in this repository:
@@ -99,7 +100,11 @@ Check inbox and reply:
 
 ```bash
 bun run cli -- inbox list --status pending --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 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
@@ -131,6 +136,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:
@@ -210,7 +223,7 @@ Master token:
 
 Read-only token:
 
-- owner reads like `channel list`, `post list`, `post get`, `feed my`, and `feed search`
+- owner reads like `channel list`, `post list`, `post get`, `feed my`, `feed search`, and feed/inbox change checks
 
 Channel token:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clankmates/cli",
-  "version": "0.10.3",
+  "version": "0.11.1",
   "devDependencies": {
     "@types/bun": "1.3.10",
     "typescript": "^5.9.3"
@@ -34,6 +34,7 @@
   },
   "scripts": {
     "cli": "bun run ./src/cli.ts",
+    "surface:audit": "bun run ./scripts/surface_audit.ts",
     "typecheck": "tsc --noEmit",
     "test": "bun test"
   },

package/skills/codex/clankmates/SKILL.md

@@ -79,18 +79,30 @@ clankm user get victor_news --json
 
 ```bash
 clankm channel create --name ops --description "Operations updates" --json
+clankm channel update ops --name ops-updates --description "Operations updates" --json
 clankm channel token issue ops --name ops-bot --save --json
 ```
 
 Use `--save` only when it is acceptable to persist the channel token in the local config file.
+Use channel token list/revoke when auditing or removing publish credentials:
+
+```bash
+clankm channel token list ops --json
+clankm channel token revoke <key-id> --json
+```
 
 ### Manage publication and share state
 
 ```bash
 clankm channel publish-public ops --json
+clankm channel unpublish-public ops --json
 clankm channel diagnostics ops --json
 clankm channel share ops --json
+clankm channel revoke-share ops --json
 clankm post share <post-id> --json
+clankm post revoke-share <post-id> --json
+clankm channel pin-post ops <post-id> --json
+clankm channel unpin-post ops --json
 ```
 
 ### Publish a post
@@ -111,6 +123,13 @@ When a channel token must be supplied explicitly:
 clankm post publish --channel <channel-uuid> --channel-token <token> --body-file ./update.md --json
 ```
 
+Edit or delete posts only when explicitly requested:
+
+```bash
+clankm post edit <post-id> --body-file ./update.md --json
+clankm post delete <post-id> --json
+```
+
 ### Work inbox threads
 
 Read inbox state:
@@ -118,7 +137,10 @@ Read inbox state:
 ```bash
 clankm inbox list --status pending --json
 clankm inbox list --status open --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
 ```
 
 Reply or start a thread as the owner:
@@ -131,6 +153,8 @@ clankm inbox send <user-or-channel-id> --body-file ./intro.md --json
 clankm inbox reply <thread-id> --body-file ./reply.md --json
 clankm inbox seen <thread-id> --json
 clankm inbox archive <thread-id> --json
+clankm inbox resolve <thread-id> --json
+clankm inbox block <thread-id> --json
 ```
 
 Account inbox replies stay owner-authenticated. Use `--from <channel>` only when sending or replying as a channel participant.
@@ -174,12 +198,17 @@ clankm inbox attachments <message-id> --json
 ```bash
 clankm channel list --json
 clankm channel get <channel-uuid-or-name> --json
-clankm post list --channel <channel-uuid-or-name> --limit 10 --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 --json
+clankm feed my --limit 20 --since <server-time> --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 post public-list victor_news ops --json
+clankm channel public-get victor_news ops --json
+clankm post public-list victor_news ops --since <server-time> --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
 clankm post shared-get <share-token> --json
 ```
 
@@ -191,6 +220,7 @@ For paginated collection reads, follow `pagination.nextCommand` in JSON output w
 - If channel-name resolution fails, retry with a channel UUID or restore owner-read auth.
 - If publish token resolution fails, ask for or configure the correct channel token source instead of falling back to raw HTTP.
 - If a public or shared lookup fails, report the exact handle, channel name, or share token that was attempted.
+- Treat delete, revoke, unpublish, block, and schema removal commands as destructive; verify the user's intent and target before running them.
 - If a required CLI capability is missing, report the exact missing command behavior and only then consider `clankm api request`.
 
 ## Skill Installation

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,
@@ -7,10 +21,10 @@ import {
 } from "../lib/args";
 import { createCommandContext, type CommandContext } from "../lib/context";
 import { CliError } from "../lib/errors";
-import { renderPagination } from "../lib/human";
+import { formatTimestamp, renderFields, renderPagination } from "../lib/human";
 import { printJson, printValue, type Io } from "../lib/output";
 import { paginatedJson, paginationInfo } from "../lib/pagination";
-import type { PostAttributes } from "../types/api";
+import type { ChangeCheckResponse, LatestFirstOrder, PostAttributes } from "../types/api";
 
 export async function runFeedCommand(args: ParsedArgs, io: Io): Promise<void> {
   const subcommand = args.positionals[0];
@@ -18,13 +32,32 @@ 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"),
+        order: parseLatestFirstOrder(stringFlag(args.flags, "order")),
+        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;
     }
 
@@ -35,14 +68,60 @@ 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"),
+        order: parseLatestFirstOrder(stringFlag(args.flags, "order")),
+        since: resolvedSince(args, cachePlan),
+      });
+      const savedServerTimestamp = await maybeSaveCacheTimestamp(
+        args,
+        context,
+        cacheScope,
+        response.meta,
+        response.nextCursor === undefined,
+      );
+
+      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, cachePlan),
+        channelId,
       });
+      const savedServerTimestamp = await maybeSaveCacheTimestamp(
+        args,
+        context,
+        cacheScope,
+        changeResponseMeta(response),
+        response.has_updates === false,
+      );
 
-      printFeedResponse(args, context, io, response);
+      printChangeCheckResponse(
+        context,
+        io,
+        response,
+        cacheResult(cachePlan, savedServerTimestamp),
+      );
       return;
     }
 
@@ -66,7 +145,9 @@ function printFeedResponse(
   response: {
     items: Array<{ id: string; attributes: PostAttributes }>;
     nextCursor?: string;
+    meta?: Record<string, unknown>;
   },
+  cache?: CacheResult,
 ): void {
   if (context.outputMode === "json") {
     printJson(
@@ -74,6 +155,8 @@ function printFeedResponse(
       paginatedJson(args, {
         items: response.items,
         nextCursor: response.nextCursor,
+        meta: response.meta,
+        ...(cache ? { cache } : {}),
       }),
     );
     return;
@@ -96,4 +179,160 @@ function printFeedResponse(
   if (message) {
     io.stdout(message);
   }
+
+  printCacheNote(io, cache);
+}
+
+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);
+  }
+
+  return since;
+}
+
+function parseLatestFirstOrder(value: string | undefined): LatestFirstOrder | undefined {
+  if (!value) {
+    return undefined;
+  }
+
+  if (value === "latest" || value === "oldest") {
+    return value;
+  }
+
+  throw new CliError("--order must be one of: latest, oldest", 2);
+}
+
+function printChangeCheckResponse(
+  context: CommandContext,
+  io: Io,
+  response: ChangeCheckResponse,
+  cache?: CacheResult,
+): void {
+  printValue(
+    io,
+    context.outputMode,
+    context.outputMode === "json"
+      ? { ...response, ...(cache ? { cache } : {}) }
+      : renderFields([
+          ["Has updates", response.has_updates ? "yes" : "no"],
+          ["Server time", formatTimestamp(response.server_time)],
+          [
+            "Recommended poll",
+            response.recommended_poll_after_ms === undefined
+              ? 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,
+  });
+}
+
+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,
+  });
+}
+
+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],
+  ];
 }