@clankmates/cli 0.11.0 → 0.11.1

package/src/lib/cache.ts

@@ -0,0 +1,499 @@
+import { Database } from "bun:sqlite";
+import { mkdir } from "node:fs/promises";
+import path from "node:path";
+import { createHash } from "node:crypto";
+
+import { booleanFlag, stringFlag, type ParsedArgs } from "./args";
+import type { CommandContext } from "./context";
+import { CliError } from "./errors";
+import { getCachePath } from "./paths";
+import { CLI_VERSION } from "./version";
+import type { WhoamiActor } from "../types/api";
+
+const MIGRATION_VERSION = 1;
+const PUBLIC_ACTOR_KEY = "public";
+const SHARED_ACTOR_KEY = "shared";
+
+export interface SyncScopeRow {
+  scope_key: string;
+  base_url: string;
+  profile: string;
+  actor_key: string;
+  resource: string;
+  params_json: string;
+  server_timestamp?: string | null;
+  cached_at: string;
+  cli_version: string;
+}
+
+export interface CacheScope {
+  scopeKey: string;
+  resource: string;
+  params: Record<string, unknown>;
+  actorKey: string;
+}
+
+export interface CachePlan {
+  scope: CacheScope;
+  previousServerTimestamp?: string;
+  hit: boolean;
+}
+
+export interface CacheResult {
+  scopeKey: string;
+  hit: boolean;
+  previousServerTimestamp?: string;
+  savedServerTimestamp?: string;
+}
+
+export class SyncCache {
+  private readonly db: Database;
+
+  constructor(private readonly dbPath = getCachePath()) {
+    this.db = new Database(dbPath, { create: true });
+    this.db.exec("PRAGMA journal_mode = WAL");
+    this.db.exec("PRAGMA foreign_keys = ON");
+    this.migrate();
+  }
+
+  path(): string {
+    return this.dbPath;
+  }
+
+  get(scopeKey: string): SyncScopeRow | undefined {
+    return this.db
+      .query<SyncScopeRow, [string]>(
+        `select scope_key, base_url, profile, actor_key, resource, params_json,
+                server_timestamp, cached_at, cli_version
+           from sync_scopes
+          where scope_key = ?`,
+      )
+      .get(scopeKey) ?? undefined;
+  }
+
+  list(input: { baseUrl?: string; profile?: string } = {}): SyncScopeRow[] {
+    if (input.baseUrl && input.profile) {
+      return this.db
+        .query<SyncScopeRow, [string, string]>(
+          `select scope_key, base_url, profile, actor_key, resource, params_json,
+                  server_timestamp, cached_at, cli_version
+             from sync_scopes
+            where base_url = ? and profile = ?
+            order by resource, scope_key`,
+        )
+        .all(input.baseUrl, input.profile);
+    }
+
+    return this.db
+      .query<SyncScopeRow, []>(
+        `select scope_key, base_url, profile, actor_key, resource, params_json,
+                server_timestamp, cached_at, cli_version
+           from sync_scopes
+          order by base_url, profile, resource, scope_key`,
+      )
+      .all();
+  }
+
+  upsert(input: {
+    scope: CacheScope;
+    baseUrl: string;
+    profile: string;
+    serverTimestamp: string;
+  }): void {
+    this.db
+      .query<
+        unknown,
+        [string, string, string, string, string, string, string, string, string]
+      >(
+        `insert into sync_scopes (
+           scope_key, base_url, profile, actor_key, resource, params_json,
+           server_timestamp, cached_at, cli_version
+         )
+         values (?, ?, ?, ?, ?, ?, ?, ?, ?)
+         on conflict(scope_key) do update set
+           base_url = excluded.base_url,
+           profile = excluded.profile,
+           actor_key = excluded.actor_key,
+           resource = excluded.resource,
+           params_json = excluded.params_json,
+           server_timestamp = excluded.server_timestamp,
+           cached_at = excluded.cached_at,
+           cli_version = excluded.cli_version`,
+      )
+      .run(
+        input.scope.scopeKey,
+        input.baseUrl,
+        input.profile,
+        input.scope.actorKey,
+        input.scope.resource,
+        stableJson(input.scope.params),
+        input.serverTimestamp,
+        new Date().toISOString(),
+        CLI_VERSION,
+      );
+  }
+
+  clear(input: { scopeKey?: string; baseUrl?: string; profile?: string } = {}): number {
+    if (input.scopeKey) {
+      const result = this.db
+        .query<unknown, [string]>("delete from sync_scopes where scope_key = ?")
+        .run(input.scopeKey);
+      return result.changes;
+    }
+
+    if (input.baseUrl && input.profile) {
+      const result = this.db
+        .query<unknown, [string, string]>(
+          "delete from sync_scopes where base_url = ? and profile = ?",
+        )
+        .run(input.baseUrl, input.profile);
+      return result.changes;
+    }
+
+    const result = this.db.query<unknown, []>("delete from sync_scopes").run();
+    return result.changes;
+  }
+
+  close(): void {
+    this.db.close();
+  }
+
+  private migrate(): void {
+    this.db.exec(`
+      create table if not exists schema_migrations (
+        version integer primary key,
+        applied_at text not null
+      );
+    `);
+
+    const applied = this.db
+      .query<{ version: number }, [number]>(
+        "select version from schema_migrations where version = ?",
+      )
+      .get(MIGRATION_VERSION);
+
+    if (applied) {
+      return;
+    }
+
+    this.db.exec(`
+      create table if not exists sync_scopes (
+        scope_key text primary key,
+        base_url text not null,
+        profile text not null,
+        actor_key text not null,
+        resource text not null,
+        params_json text not null,
+        server_timestamp text,
+        cached_at text not null,
+        cli_version text not null
+      );
+
+      create index if not exists sync_scopes_profile_idx
+        on sync_scopes(base_url, profile);
+    `);
+
+    this.db
+      .query<unknown, [number, string]>(
+        "insert into schema_migrations(version, applied_at) values (?, ?)",
+      )
+      .run(MIGRATION_VERSION, new Date().toISOString());
+  }
+}
+
+export async function ensureCacheParentDirectory(cachePath = getCachePath()): Promise<void> {
+  await mkdir(path.dirname(cachePath), { recursive: true });
+}
+
+export async function openSyncCache(cachePath = getCachePath()): Promise<SyncCache> {
+  await ensureCacheParentDirectory(cachePath);
+  return new SyncCache(cachePath);
+}
+
+export function cacheFlags(args: ParsedArgs): {
+  sinceCache: boolean;
+  saveCache: boolean;
+} {
+  return {
+    sinceCache: booleanFlag(args.flags, "sinceCache"),
+    saveCache: booleanFlag(args.flags, "saveCache"),
+  };
+}
+
+export function assertSinceFlags(args: ParsedArgs): void {
+  if (stringFlag(args.flags, "since") && booleanFlag(args.flags, "sinceCache")) {
+    throw new CliError("Use only one of `--since` or `--since-cache`", 2);
+  }
+}
+
+export async function prepareCachePlan(
+  context: CommandContext,
+  scope: CacheScope,
+): Promise<CachePlan> {
+  const cache = await openSyncCache();
+
+  try {
+    const row = cache.get(scope.scopeKey);
+    return {
+      scope,
+      previousServerTimestamp: row?.server_timestamp ?? undefined,
+      hit: Boolean(row?.server_timestamp),
+    };
+  } finally {
+    cache.close();
+  }
+}
+
+export async function saveCacheTimestamp(
+  context: CommandContext,
+  scope: CacheScope,
+  meta: Record<string, unknown> | undefined,
+): Promise<string | undefined> {
+  const serverTimestamp = extractServerTimestamp(meta);
+
+  if (!serverTimestamp) {
+    return undefined;
+  }
+
+  const cache = await openSyncCache();
+
+  try {
+    cache.upsert({
+      scope,
+      baseUrl: context.profile.baseUrl,
+      profile: context.profileName,
+      serverTimestamp,
+    });
+  } finally {
+    cache.close();
+  }
+
+  return serverTimestamp;
+}
+
+export function cacheResult(
+  plan: CachePlan | undefined,
+  savedServerTimestamp?: string,
+): CacheResult | undefined {
+  if (!plan && !savedServerTimestamp) {
+    return undefined;
+  }
+
+  return {
+    scopeKey: plan?.scope.scopeKey ?? "",
+    hit: plan?.hit ?? false,
+    previousServerTimestamp: plan?.previousServerTimestamp,
+    savedServerTimestamp,
+  };
+}
+
+export function extractServerTimestamp(
+  meta: Record<string, unknown> | undefined,
+): string | undefined {
+  if (!meta) {
+    return undefined;
+  }
+
+  for (const key of [
+    "server_time",
+    "server_timestamp",
+    "serverTimestamp",
+    "latest_server_timestamp",
+    "latestServerTimestamp",
+  ]) {
+    const value = meta[key];
+
+    if (typeof value === "string" && value.length > 0) {
+      return value;
+    }
+  }
+
+  return undefined;
+}
+
+export function changeResponseMeta(response: {
+  server_time?: string;
+}): Record<string, unknown> {
+  return response.server_time ? { server_time: response.server_time } : {};
+}
+
+export async function authenticatedActorKey(
+  context: CommandContext,
+  channelToken?: string,
+): Promise<string> {
+  return actorKey((await context.client.whoami(channelToken)).actor);
+}
+
+export function publicActorKey(): string {
+  return PUBLIC_ACTOR_KEY;
+}
+
+export function sharedActorKey(): string {
+  return SHARED_ACTOR_KEY;
+}
+
+export function feedMyScope(input: {
+  context: CommandContext;
+  actorKey: string;
+  channelId?: string;
+}): CacheScope {
+  const channel = input.channelId ?? "all";
+  return scoped({
+    context: input.context,
+    actorKey: input.actorKey,
+    resource: "feed:my",
+    parts: ["feed", "my", channel],
+    params: { channel },
+  });
+}
+
+export function feedSearchScope(input: {
+  context: CommandContext;
+  actorKey: string;
+  query: string;
+  channelId?: string;
+}): CacheScope {
+  const channel = input.channelId ?? "all";
+  return scoped({
+    context: input.context,
+    actorKey: input.actorKey,
+    resource: "feed:search",
+    parts: ["feed", "search", input.query, channel],
+    params: { query: input.query, channel },
+  });
+}
+
+export function inboxThreadsScope(input: {
+  context: CommandContext;
+  actorKey: string;
+  status?: string;
+  mailbox?: string;
+}): CacheScope {
+  const status = input.status ?? "default";
+  const mailbox = input.mailbox ?? "default";
+  return scoped({
+    context: input.context,
+    actorKey: input.actorKey,
+    resource: "inbox:threads",
+    parts: ["inbox", "threads", status, mailbox, input.actorKey],
+    params: { status, mailbox },
+  });
+}
+
+export function inboxMessagesScope(input: {
+  context: CommandContext;
+  actorKey: string;
+  threadId: string;
+}): CacheScope {
+  return scoped({
+    context: input.context,
+    actorKey: input.actorKey,
+    resource: "inbox:messages",
+    parts: ["inbox", "messages", input.threadId, input.actorKey],
+    params: { threadId: input.threadId },
+  });
+}
+
+export function ownedPostsScope(input: {
+  context: CommandContext;
+  actorKey: string;
+  channelId: string;
+}): CacheScope {
+  return scoped({
+    context: input.context,
+    actorKey: input.actorKey,
+    resource: "posts:owned",
+    parts: ["posts", "owned", input.channelId],
+    params: { channelId: input.channelId },
+  });
+}
+
+export function publicPostsScope(input: {
+  context: CommandContext;
+  publicHandle: string;
+  channelName: string;
+}): CacheScope {
+  return scoped({
+    context: input.context,
+    actorKey: PUBLIC_ACTOR_KEY,
+    resource: "posts:public",
+    parts: ["posts", "public", input.publicHandle, input.channelName],
+    params: {
+      publicHandle: input.publicHandle,
+      channelName: input.channelName,
+    },
+  });
+}
+
+export function sharedPostsScope(input: {
+  context: CommandContext;
+  shareToken: string;
+}): CacheScope {
+  const shareTokenHash = hashValue(input.shareToken);
+  return scoped({
+    context: input.context,
+    actorKey: SHARED_ACTOR_KEY,
+    resource: "posts:shared",
+    parts: ["posts", "shared", shareTokenHash],
+    params: { shareTokenHash },
+  });
+}
+
+export function hashValue(value: string): string {
+  return createHash("sha256").update(value).digest("hex");
+}
+
+function actorKey(actor: WhoamiActor): string {
+  if (actor.type === "user") {
+    return `user:${actor.id}:${actor.scope ?? "master"}`;
+  }
+
+  return `channel:${actor.id}`;
+}
+
+function scoped(input: {
+  context: CommandContext;
+  actorKey: string;
+  resource: string;
+  parts: string[];
+  params: Record<string, unknown>;
+}): CacheScope {
+  const prefix = [
+    "v1",
+    normalizePart(input.context.profile.baseUrl),
+    normalizePart(input.context.profileName),
+    normalizePart(input.actorKey),
+  ];
+  const scopeKey = [...prefix, ...input.parts.map(normalizePart)].join(":");
+
+  return {
+    scopeKey,
+    resource: input.resource,
+    params: input.params,
+    actorKey: input.actorKey,
+  };
+}
+
+function normalizePart(value: string): string {
+  return encodeURIComponent(value);
+}
+
+function stableJson(value: Record<string, unknown>): string {
+  return JSON.stringify(sortObject(value));
+}
+
+function sortObject(value: unknown): unknown {
+  if (Array.isArray(value)) {
+    return value.map(sortObject);
+  }
+
+  if (typeof value !== "object" || value === null) {
+    return value;
+  }
+
+  return Object.fromEntries(
+    Object.entries(value as Record<string, unknown>)
+      .sort(([left], [right]) => left.localeCompare(right))
+      .map(([key, entry]) => [key, sortObject(entry)]),
+  );
+}

package/src/lib/help.ts

@@ -99,6 +99,14 @@ 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.",
@@ -350,6 +358,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 +635,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] [--save-cache] [--limit <n>] [--cursor <cursor>] [--profile <name>] [--json]`,
           {
             options: [
               option(
@@ -596,6 +644,8 @@ const HELP_ROOT = group(
               ),
               ORDER_OPTION,
               SINCE_OPTION,
+              SINCE_CACHE_OPTION,
+              SAVE_CACHE_OPTION,
               LIMIT_OPTION,
               CURSOR_OPTION,
               PROFILE_OPTION,
@@ -630,11 +680,13 @@ 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] [--save-cache] [--limit <n>] [--cursor <cursor>] [--profile <name>] [--json]`,
           {
             options: [
               ORDER_OPTION,
               SINCE_OPTION,
+              SINCE_CACHE_OPTION,
+              SAVE_CACHE_OPTION,
               LIMIT_OPTION,
               CURSOR_OPTION,
               PROFILE_OPTION,
@@ -653,11 +705,13 @@ 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] [--save-cache] [--limit <n>] [--cursor <cursor>] [--profile <name>] [--json]`,
           {
             options: [
               ORDER_OPTION,
               SINCE_OPTION,
+              SINCE_CACHE_OPTION,
+              SAVE_CACHE_OPTION,
               LIMIT_OPTION,
               CURSOR_OPTION,
               PROFILE_OPTION,
@@ -708,7 +762,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] [--save-cache] [--limit <n>] [--cursor <cursor>] [--profile <name>] [--json]`,
           {
             options: [
               option(
@@ -717,6 +771,8 @@ const HELP_ROOT = group(
               ),
               ORDER_OPTION,
               SINCE_OPTION,
+              SINCE_CACHE_OPTION,
+              SAVE_CACHE_OPTION,
               LIMIT_OPTION,
               CURSOR_OPTION,
               PROFILE_OPTION,
@@ -727,7 +783,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] [--save-cache] [--limit <n>] [--cursor <cursor>] [--profile <name>] [--json]`,
           {
             options: [
               option(
@@ -736,6 +792,8 @@ const HELP_ROOT = group(
               ),
               ORDER_OPTION,
               SINCE_OPTION,
+              SINCE_CACHE_OPTION,
+              SAVE_CACHE_OPTION,
               LIMIT_OPTION,
               CURSOR_OPTION,
               PROFILE_OPTION,
@@ -746,10 +804,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 +831,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>] [--order <latest|oldest>] [--since <server-time>|--since-cache] [--save-cache] [--limit <n>] [--cursor <cursor>] [--channel-token <token>] [--profile <name>] [--json]`,
           {
             options: [
               option(
@@ -784,6 +844,8 @@ const HELP_ROOT = group(
               ),
               ORDER_OPTION,
               SINCE_OPTION,
+              SINCE_CACHE_OPTION,
+              SAVE_CACHE_OPTION,
               LIMIT_OPTION,
               CURSOR_OPTION,
               CHANNEL_TOKEN_OPTION,
@@ -795,11 +857,13 @@ 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] [--save-cache] [--limit <n>] [--cursor <cursor>] [--channel-token <token>] [--profile <name>] [--json]`,
           {
             options: [
               ORDER_OPTION,
               SINCE_OPTION,
+              SINCE_CACHE_OPTION,
+              SAVE_CACHE_OPTION,
               LIMIT_OPTION,
               CURSOR_OPTION,
               CHANNEL_TOKEN_OPTION,
@@ -811,10 +875,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>] [--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.",
@@ -836,10 +902,12 @@ 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] [--channel-token <token>] [--profile <name>] [--json]`,
               {
                 options: [
                   SINCE_OPTION,
+                  SINCE_CACHE_OPTION,
+                  SAVE_CACHE_OPTION,
                   CHANNEL_TOKEN_OPTION,
                   PROFILE_OPTION,
                   JSON_OPTION,