@clankmates/cli 0.12.0 → 0.13.0

package/src/commands/post.ts

@@ -4,12 +4,8 @@ import {
   cacheFlags,
   cacheResult,
   ownedPostsScope,
-  prepareCachePlan,
   publicPostsScope,
-  saveCacheTimestamp,
   sharedPostsScope,
-  type CachePlan,
-  type CacheResult,
   type CacheScope,
 } from "../lib/cache";
 import {
@@ -28,11 +24,16 @@ import {
   renderFields,
   formatTimestamp,
   joinBlocks,
-  renderPagination,
 } from "../lib/human";
-import { printJson, printValue, type Io } from "../lib/output";
-import { paginatedJson, paginationInfo } from "../lib/pagination";
-import type { LatestFirstOrder, PostAttributes, ShareTokenResponse } from "../types/api";
+import { printValue, type Io } from "../lib/output";
+import {
+  maybePrepareCachePlan,
+  maybeSaveCacheTimestamp,
+  parseLatestFirstOrder,
+  resolvedSince,
+} from "../lib/polling";
+import { printPostCollection } from "../lib/post-output";
+import type { PostAttributes, ShareTokenResponse } from "../types/api";
 
 export async function runPostCommand(args: ParsedArgs, io: Io): Promise<void> {
   const subcommand = args.positionals[0];
@@ -299,88 +300,6 @@ export async function runPostCommand(args: ParsedArgs, io: Io): Promise<void> {
   }
 }
 
-function printPostCollection(
-  args: ParsedArgs,
-  outputMode: "json" | "table",
-  io: Io,
-  response: {
-    items: Array<{ id: string; attributes: PostAttributes }>;
-    nextCursor?: string;
-    meta?: Record<string, unknown>;
-  },
-  cache?: CacheResult,
-): void {
-  if (outputMode === "json") {
-    printJson(
-      io,
-      paginatedJson(args, {
-        items: response.items,
-        nextCursor: response.nextCursor,
-        meta: response.meta,
-        ...(cache ? { cache } : {}),
-      }),
-    );
-    return;
-  }
-
-  printValue(
-    io,
-    outputMode,
-    response.items.map((item) => ({
-      id: item.id,
-      source: item.attributes.source,
-      date: item.attributes.updated_at ?? item.attributes.inserted_at ?? "",
-      body: item.attributes.body,
-    })),
-  );
-
-  const pagination = paginationInfo(args, response.nextCursor);
-  const message = renderPagination(
-    pagination?.nextCursor,
-    pagination?.nextCommand,
-  );
-
-  if (message) {
-    io.stdout(message);
-  }
-
-  printCacheNote(io, cache);
-}
-
-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);
-}
-
-async function maybePrepareCachePlan(
-  args: ParsedArgs,
-  context: Awaited<ReturnType<typeof createCommandContext>>,
-  scope: CacheScope | undefined,
-): Promise<CachePlan | undefined> {
-  return cacheFlags(args).sinceCache && scope
-    ? prepareCachePlan(context, scope)
-    : undefined;
-}
-
-async function maybeSaveCacheTimestamp(
-  args: ParsedArgs,
-  context: Awaited<ReturnType<typeof createCommandContext>>,
-  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 maybeOwnedPostsScope(
   args: ParsedArgs,
   context: Awaited<ReturnType<typeof createCommandContext>>,
@@ -432,30 +351,6 @@ function maybeSharedPostsScope(
   });
 }
 
-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 renderPostDetail(
   post: { id: string; attributes: PostAttributes },
   options: { title?: string; channelId?: string } = {},

package/src/lib/args.ts

@@ -56,6 +56,7 @@ const CLI_OPTIONS = {
   "since-cache": { type: "boolean" },
   saveCache: { type: "boolean" },
   "save-cache": { type: "boolean" },
+  once: { type: "boolean" },
   status: { type: "string" },
   mailbox: { type: "string" },
   participant: { type: "string" },

package/src/lib/cache/scopes.ts

@@ -0,0 +1,216 @@
+import { createHash } from "node:crypto";
+
+import type { CommandContext } from "../context";
+import type { WhoamiActor } from "../../types/api";
+import type { CacheScope } from "./types";
+
+const PUBLIC_ACTOR_KEY = "public";
+const SHARED_ACTOR_KEY = "shared";
+
+export function actorKey(actor: WhoamiActor): string {
+  if (actor.type === "user") {
+    return `user:${actor.id}:${actor.scope ?? "master"}`;
+  }
+
+  return `channel:${actor.id}`;
+}
+
+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;
+  before?: string;
+}): CacheScope {
+  const channel = input.channelId ?? "all";
+  const before = input.before ?? "default";
+  return scoped({
+    context: input.context,
+    actorKey: input.actorKey,
+    resource: "feed:my",
+    parts: ["feed", "my", channel, before],
+    params: { channel, before },
+  });
+}
+
+export function feedSearchScope(input: {
+  context: CommandContext;
+  actorKey: string;
+  query: string;
+  channelId?: string;
+  before?: string;
+}): CacheScope {
+  const channel = input.channelId ?? "all";
+  const before = input.before ?? "default";
+  return scoped({
+    context: input.context,
+    actorKey: input.actorKey,
+    resource: "feed:search",
+    parts: ["feed", "search", input.query, channel, before],
+    params: { query: input.query, channel, before },
+  });
+}
+
+export function inboxThreadsScope(input: {
+  context: CommandContext;
+  actorKey: string;
+  status?: string;
+  mailbox?: string;
+  participant?: string;
+  participantScope?: string;
+  query?: string;
+  hasAttachment?: boolean;
+  before?: string;
+}): CacheScope {
+  const status = input.status ?? "default";
+  const mailbox = input.mailbox ?? "default";
+  const participant = input.participant ?? "default";
+  const participantScope = input.participantScope ?? "default";
+  const query = input.query ?? "default";
+  const hasAttachment = input.hasAttachment ?? false;
+  const before = input.before ?? "default";
+  return scoped({
+    context: input.context,
+    actorKey: input.actorKey,
+    resource: "inbox:threads",
+    parts: [
+      "inbox",
+      "threads",
+      status,
+      mailbox,
+      participant,
+      participantScope,
+      query,
+      String(hasAttachment),
+      before,
+      input.actorKey,
+    ],
+    params: {
+      status,
+      mailbox,
+      participant,
+      participantScope,
+      query,
+      hasAttachment,
+      before,
+    },
+  });
+}
+
+export function inboxMessagesScope(input: {
+  context: CommandContext;
+  actorKey: string;
+  threadId: string;
+  query?: string;
+  hasAttachment?: boolean;
+  before?: string;
+}): CacheScope {
+  const query = input.query ?? "default";
+  const hasAttachment = input.hasAttachment ?? false;
+  const before = input.before ?? "default";
+  return scoped({
+    context: input.context,
+    actorKey: input.actorKey,
+    resource: "inbox:messages",
+    parts: [
+      "inbox",
+      "messages",
+      input.threadId,
+      query,
+      String(hasAttachment),
+      before,
+      input.actorKey,
+    ],
+    params: { threadId: input.threadId, query, hasAttachment, before },
+  });
+}
+
+export function ownedPostsScope(input: {
+  context: CommandContext;
+  actorKey: string;
+  channelId: string;
+  before?: string;
+}): CacheScope {
+  const before = input.before ?? "default";
+  return scoped({
+    context: input.context,
+    actorKey: input.actorKey,
+    resource: "posts:owned",
+    parts: ["posts", "owned", input.channelId, before],
+    params: { channelId: input.channelId, before },
+  });
+}
+
+export function publicPostsScope(input: {
+  context: CommandContext;
+  publicHandle: string;
+  channelName: string;
+  before?: string;
+}): CacheScope {
+  const before = input.before ?? "default";
+  return scoped({
+    context: input.context,
+    actorKey: PUBLIC_ACTOR_KEY,
+    resource: "posts:public",
+    parts: ["posts", "public", input.publicHandle, input.channelName, before],
+    params: {
+      publicHandle: input.publicHandle,
+      channelName: input.channelName,
+      before,
+    },
+  });
+}
+
+export function sharedPostsScope(input: {
+  context: CommandContext;
+  shareToken: string;
+  before?: string;
+}): CacheScope {
+  const shareTokenHash = hashValue(input.shareToken);
+  const before = input.before ?? "default";
+  return scoped({
+    context: input.context,
+    actorKey: SHARED_ACTOR_KEY,
+    resource: "posts:shared",
+    parts: ["posts", "shared", shareTokenHash, before],
+    params: { shareTokenHash, before },
+  });
+}
+
+export function hashValue(value: string): string {
+  return createHash("sha256").update(value).digest("hex");
+}
+
+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);
+}

package/src/lib/cache/store.ts

@@ -0,0 +1,195 @@
+import { Database } from "bun:sqlite";
+import { mkdir } from "node:fs/promises";
+import path from "node:path";
+
+import { getCachePath } from "../paths";
+import { CLI_VERSION } from "../version";
+import type { CacheScope, SyncScopeRow } from "./types";
+
+const MIGRATION_VERSION = 1;
+
+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);
+}
+
+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/cache/types.ts

@@ -0,0 +1,31 @@
+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;
+}