@clankid/cli 0.17.0

package/src/lib/pagination.ts

@@ -0,0 +1,116 @@
+import type { ParsedArgs } from "./args";
+
+const CLI_NAME = "clank";
+
+const PAGINATION_FLAG_ORDER: Array<
+  [key: string, flag: string]
+> = [
+  ["profile", "--profile"],
+  ["baseUrl", "--base-url"],
+  ["identity", "--identity"],
+  ["identityId", "--identity"],
+  ["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;
+}
+
+export function paginationInfo(
+  args: ParsedArgs,
+  nextCursor?: string | null,
+  options: { json?: boolean } = {},
+): PaginationInfo | undefined {
+  if (!nextCursor) {
+    return undefined;
+  }
+
+  return {
+    nextCursor,
+    nextCommand: args.flags.identityKey
+      ? undefined
+      : nextCommand(args, nextCursor, options),
+  };
+}
+
+export function paginatedJson<T extends object>(
+  args: ParsedArgs,
+  response: T & { nextCursor?: string },
+): T & { nextCursor?: string; pagination?: PaginationInfo } {
+  return {
+    ...response,
+    pagination: paginationInfo(args, response.nextCursor, { json: true }),
+  };
+}
+
+function paginationFlagParts(args: ParsedArgs): string[] {
+  const parts: string[] = [];
+  const seenFlags = new Set<string>();
+
+  for (const [key, flag] of PAGINATION_FLAG_ORDER) {
+    if (seenFlags.has(flag)) {
+      continue;
+    }
+
+    const value = args.flags[key];
+
+    if (typeof value !== "string") {
+      continue;
+    }
+
+    parts.push(flag, value);
+    seenFlags.add(flag);
+  }
+
+  for (const [key, flag] of PAGINATION_BOOLEAN_FLAGS) {
+    if (args.flags[key] === true) {
+      parts.push(flag);
+    }
+  }
+
+  return parts;
+}
+
+function nextCommand(
+  args: ParsedArgs,
+  nextCursor: string,
+  options: { json?: boolean },
+): string {
+  const parts = [
+    CLI_NAME,
+    ...args.commandPath,
+    ...args.positionals,
+    ...paginationFlagParts(args),
+    "--cursor",
+    nextCursor,
+  ];
+
+  if (options.json) {
+    parts.push("--json");
+  }
+
+  return parts.map(shellQuote).join(" ");
+}
+
+function shellQuote(value: string): string {
+  if (/^[A-Za-z0-9_./:@%+=,-]+$/.test(value)) {
+    return value;
+  }
+
+  return `'${value.replace(/'/g, "'\\''")}'`;
+}

package/src/lib/paths.ts

@@ -0,0 +1,44 @@
+import os from "node:os";
+import path from "node:path";
+
+export function getConfigPath(): string {
+  const explicit = process.env.CLANKID_CONFIG_PATH;
+
+  if (explicit) {
+    return explicit;
+  }
+
+  const xdg = process.env.XDG_CONFIG_HOME;
+
+  if (xdg) {
+    return path.join(xdg, "clankid", "config.json");
+  }
+
+  return path.join(os.homedir(), ".config", "clankid", "config.json");
+}
+
+export function getCachePath(): string {
+  const explicit = process.env.CLANKID_CACHE_PATH;
+
+  if (explicit) {
+    return explicit;
+  }
+
+  const xdg = process.env.XDG_CACHE_HOME;
+
+  if (xdg) {
+    return path.join(xdg, "clankid", "clank-cache.sqlite");
+  }
+
+  if (process.platform === "darwin") {
+    return path.join(
+      os.homedir(),
+      "Library",
+      "Caches",
+      "clankid",
+      "clank-cache.sqlite",
+    );
+  }
+
+  return path.join(os.homedir(), ".cache", "clankid", "clank-cache.sqlite");
+}

package/src/lib/polling.ts

@@ -0,0 +1,146 @@
+import {
+  cacheFlags,
+  prepareCachePlan,
+  saveCacheTimestamp,
+  type CachePlan,
+  type CacheResult,
+  type CacheScope,
+} from "./cache";
+import { stringFlag, type ParsedArgs } from "./args";
+import type { CommandContext } from "./context";
+import { CliError } from "./errors";
+import { formatTimestamp, renderFields } from "./human";
+import { printValue, type Io } from "./output";
+import type { ChangeCheckResponse, LatestFirstOrder } from "../types/api";
+
+export 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);
+}
+
+export function requiredSince(
+  args: ParsedArgs,
+  cachePlan?: CachePlan,
+  label = "resource",
+): 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 ${label} scope. Run a read command with \`--save-cache\` first.`,
+      2,
+    );
+  }
+
+  throw new CliError("Missing `--since`", 2);
+}
+
+export function resolvedSince(
+  args: ParsedArgs,
+  cachePlan: CachePlan | undefined,
+): string | undefined {
+  return stringFlag(args.flags, "since") ?? cachePlan?.previousServerTimestamp;
+}
+
+export async function maybePrepareCachePlan(
+  args: ParsedArgs,
+  context: CommandContext,
+  scope: CacheScope | undefined,
+): Promise<CachePlan | undefined> {
+  return cacheFlags(args).sinceCache && scope
+    ? prepareCachePlan(context, scope)
+    : undefined;
+}
+
+export 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;
+}
+
+export function renderCacheNote(cache: CacheResult | undefined): string | undefined {
+  if (!cache) {
+    return undefined;
+  }
+
+  const details = [
+    cache.previousServerTimestamp
+      ? `used ${cache.previousServerTimestamp}`
+      : cache.hit
+        ? "used cache"
+        : "no cached timestamp",
+    cache.savedServerTimestamp ? `saved ${cache.savedServerTimestamp}` : undefined,
+  ].filter(Boolean);
+
+  return `Cache: ${details.join("; ")}.`;
+}
+
+export function printCacheNote(io: Io, cache: CacheResult | undefined): void {
+  const note = renderCacheNote(cache);
+
+  if (note) {
+    io.stdout(note);
+  }
+}
+
+export 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],
+  ];
+}
+
+export 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),
+        ]),
+  );
+}

package/src/lib/post-output.ts

@@ -0,0 +1,60 @@
+import type { CacheResult } from "./cache";
+import { renderPagination } from "./human";
+import { printJson, printValue, type Io } from "./output";
+import { paginatedJson, paginationInfo } from "./pagination";
+import { printCacheNote } from "./polling";
+import type { ParsedArgs } from "./args";
+import type { OutputMode, PostAttributes } from "../types/api";
+
+export function printPostCollection(
+  args: ParsedArgs,
+  outputMode: OutputMode,
+  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,
+      content: item.attributes.content_format ?? "markdown",
+      date: item.attributes.updated_at ?? item.attributes.inserted_at ?? "",
+      body: item.attributes.body || payloadSummary(item.attributes.payload),
+    })),
+  );
+
+  const pagination = paginationInfo(args, response.nextCursor);
+  const message = renderPagination(
+    pagination?.nextCursor,
+    pagination?.nextCommand,
+  );
+
+  if (message) {
+    io.stdout(message);
+  }
+
+  printCacheNote(io, cache);
+}
+
+function payloadSummary(payload?: Record<string, unknown> | null): string {
+  return payload ? JSON.stringify(payload) : "";
+}

package/src/lib/skills.ts

@@ -0,0 +1,137 @@
+import { cp, lstat, mkdir, readlink, rm, symlink } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { CliError } from "./errors";
+
+export type SkillHost = "codex" | "claude" | "both";
+export type SkillInstallMode = "symlink" | "copy";
+
+export interface InstalledSkillTarget {
+  host: Exclude<SkillHost, "both">;
+  mode: SkillInstallMode;
+  sourcePath: string;
+  targetPath: string;
+  status: "installed" | "updated" | "already_installed";
+}
+
+const SKILL_NAME = "clankid";
+
+export function bundledSkillPath(): string {
+  return fileURLToPath(
+    new URL("../../skills/codex/clankid", import.meta.url),
+  );
+}
+
+export function resolveSkillHosts(host: string | undefined): Exclude<SkillHost, "both">[] {
+  switch (host ?? "both") {
+    case "codex":
+      return ["codex"];
+    case "claude":
+    case "claude-code":
+      return ["claude"];
+    case "both":
+      return ["codex", "claude"];
+    default:
+      throw new CliError(
+        "Unsupported `--host`. Use `codex`, `claude`, or `both`.",
+        2,
+      );
+  }
+}
+
+export function resolveSkillInstallTarget(host: Exclude<SkillHost, "both">): string {
+  if (host === "codex") {
+    const codexHome = process.env.CODEX_HOME || path.join(os.homedir(), ".codex");
+    return path.join(codexHome, "skills", SKILL_NAME);
+  }
+
+  const claudeHome = process.env.CLAUDE_HOME || path.join(os.homedir(), ".claude");
+  return path.join(claudeHome, "skills", SKILL_NAME);
+}
+
+export async function installBundledSkill(input: {
+  host: Exclude<SkillHost, "both">;
+  mode: SkillInstallMode;
+  force: boolean;
+}): Promise<InstalledSkillTarget> {
+  const sourcePath = bundledSkillPath();
+  const targetPath = resolveSkillInstallTarget(input.host);
+  const existing = await readInstallState(targetPath);
+
+  if (existing.exists) {
+    if (input.mode === "symlink" && existing.kind === "symlink" && existing.linkTarget === sourcePath) {
+      return {
+        host: input.host,
+        mode: input.mode,
+        sourcePath,
+        targetPath,
+        status: "already_installed",
+      };
+    }
+
+    if (!input.force) {
+      throw new CliError(
+        `Skill target already exists at ${targetPath}. Re-run with \`--force\` to replace it.`,
+        2,
+      );
+    }
+
+    await rm(targetPath, { recursive: true, force: true });
+  }
+
+  await mkdir(path.dirname(targetPath), { recursive: true });
+
+  if (input.mode === "copy") {
+    await cp(sourcePath, targetPath, { recursive: true });
+  } else {
+    await symlink(sourcePath, targetPath, "dir");
+  }
+
+  return {
+    host: input.host,
+    mode: input.mode,
+    sourcePath,
+    targetPath,
+    status: existing.exists ? "updated" : "installed",
+  };
+}
+
+async function readInstallState(targetPath: string): Promise<{
+  exists: boolean;
+  kind?: "directory" | "symlink" | "file";
+  linkTarget?: string;
+}> {
+  try {
+    const stats = await lstat(targetPath);
+
+    if (stats.isSymbolicLink()) {
+      return {
+        exists: true,
+        kind: "symlink",
+        linkTarget: await readlink(targetPath),
+      };
+    }
+
+    if (stats.isDirectory()) {
+      return {
+        exists: true,
+        kind: "directory",
+      };
+    }
+
+    return {
+      exists: true,
+      kind: "file",
+    };
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") {
+      return { exists: false };
+    }
+
+    throw new CliError(
+      `Failed to inspect skill target ${targetPath}: ${(error as Error).message}`,
+    );
+  }
+}