@clankid/cli 0.17.0

package/src/commands/post.ts

@@ -0,0 +1,406 @@
+import {
+  assertSinceFlags,
+  authenticatedActorKey,
+  cacheFlags,
+  cacheResult,
+  ownedPostsScope,
+  publicPostsScope,
+  sharedPostsScope,
+  type CacheScope,
+} from "../lib/cache";
+import {
+  booleanFlag,
+  integerFlag,
+  requiredIdentityFlag,
+  requiredPositional,
+  stringFlag,
+  type ParsedArgs,
+} from "../lib/args";
+import { payloadFilters, resolveStructuredContentInput } from "../lib/content";
+import { createCommandContext } from "../lib/context";
+import { CliError } from "../lib/errors";
+import {
+  renderBodyBlock,
+  renderFields,
+  formatTimestamp,
+  indent,
+  joinBlocks,
+} from "../lib/human";
+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];
+  const context = await createCommandContext(args, io);
+
+  switch (subcommand) {
+    case "publish": {
+      const identityId = await context.client.resolveIdentityId(
+        requiredIdentityFlag(args.flags),
+      );
+      const content = await resolveStructuredContentInput(args, {
+        requireContent: true,
+      });
+      const post = await context.client.publishPost({
+        identityId,
+        ...content,
+        identityKey: stringFlag(args.flags, "identityKey"),
+      });
+
+      printValue(
+        io,
+        context.outputMode,
+        context.outputMode === "json"
+          ? post
+          : renderPostDetail(post, { identityId, title: "Published post" }),
+      );
+      return;
+    }
+
+    case "list": {
+      assertSinceFlags(args);
+      const identityId = await context.client.resolveIdentityId(
+        requiredIdentityFlag(args.flags),
+      );
+      const cacheScope = await maybeOwnedPostsScope(args, context, identityId);
+      const cachePlan = await maybePrepareCachePlan(args, context, cacheScope);
+      const response = await context.client.listIdentityPosts({
+        identityId,
+        ...payloadFilters(args),
+        limit: integerFlag(args.flags, "limit", { label: "--limit" }),
+        cursor: stringFlag(args.flags, "cursor"),
+        before: stringFlag(args.flags, "before"),
+        order: parseLatestFirstOrder(stringFlag(args.flags, "order")),
+        since: resolvedSince(args, cachePlan),
+      });
+      const savedServerTimestamp = await maybeSaveCacheTimestamp(
+        args,
+        context,
+        cacheScope,
+        response.meta,
+        response.nextCursor === undefined,
+      );
+
+      printPostCollection(
+        args,
+        context.outputMode,
+        io,
+        response,
+        cacheResult(cachePlan, savedServerTimestamp),
+      );
+      return;
+    }
+
+    case "public-list": {
+      assertSinceFlags(args);
+      const publicHandle = requiredPositional(
+        args.positionals,
+        1,
+        "Missing public handle",
+      );
+      const identityName = requiredPositional(
+        args.positionals,
+        2,
+        "Missing public identity name",
+      );
+      const cacheScope = maybePublicPostsScope(
+        args,
+        context,
+        publicHandle,
+        identityName,
+      );
+      const cachePlan = await maybePrepareCachePlan(args, context, cacheScope);
+      const response = await context.client.listPublicIdentityPosts({
+        publicHandle,
+        identityName,
+        ...payloadFilters(args),
+        limit: integerFlag(args.flags, "limit", { label: "--limit" }),
+        cursor: stringFlag(args.flags, "cursor"),
+        before: stringFlag(args.flags, "before"),
+        order: parseLatestFirstOrder(stringFlag(args.flags, "order")),
+        since: resolvedSince(args, cachePlan),
+      });
+      const savedServerTimestamp = await maybeSaveCacheTimestamp(
+        args,
+        context,
+        cacheScope,
+        response.meta,
+        response.nextCursor === undefined,
+      );
+
+      printPostCollection(
+        args,
+        context.outputMode,
+        io,
+        response,
+        cacheResult(cachePlan, savedServerTimestamp),
+      );
+      return;
+    }
+
+    case "shared-list": {
+      assertSinceFlags(args);
+      const token = requiredPositional(args.positionals, 1, "Missing share token");
+      const cacheScope = maybeSharedPostsScope(args, context, token);
+      const cachePlan = await maybePrepareCachePlan(args, context, cacheScope);
+      const response = await context.client.listSharedIdentityPosts({
+        token,
+        ...payloadFilters(args),
+        limit: integerFlag(args.flags, "limit", { label: "--limit" }),
+        cursor: stringFlag(args.flags, "cursor"),
+        before: stringFlag(args.flags, "before"),
+        order: parseLatestFirstOrder(stringFlag(args.flags, "order")),
+        since: resolvedSince(args, cachePlan),
+      });
+      const savedServerTimestamp = await maybeSaveCacheTimestamp(
+        args,
+        context,
+        cacheScope,
+        response.meta,
+        response.nextCursor === undefined,
+      );
+
+      printPostCollection(
+        args,
+        context.outputMode,
+        io,
+        response,
+        cacheResult(cachePlan, savedServerTimestamp),
+      );
+      return;
+    }
+
+    case "edit": {
+      const post = await context.client.editPost({
+        postId: requiredPositional(args.positionals, 1, "Missing post id"),
+        ...(await resolveStructuredContentInput(args, { requireContent: true })),
+        identityKey: stringFlag(args.flags, "identityKey"),
+      });
+
+      printValue(
+        io,
+        context.outputMode,
+        context.outputMode === "json"
+          ? post
+          : renderPostDetail(post, { title: "Updated post" }),
+      );
+      return;
+    }
+
+    case "delete": {
+      const postId = requiredPositional(args.positionals, 1, "Missing post id");
+      await context.client.deletePost({
+        postId,
+        identityKey: stringFlag(args.flags, "identityKey"),
+      });
+
+      printValue(
+        io,
+        context.outputMode,
+        context.outputMode === "json"
+          ? { ok: true, id: postId }
+          : `Deleted post ${postId}.`,
+      );
+      return;
+    }
+
+    case "get": {
+      const post = await context.client.getPost(
+        requiredPositional(args.positionals, 1, "Missing post id"),
+      );
+
+      printValue(
+        io,
+        context.outputMode,
+        context.outputMode === "json"
+          ? post
+          : renderPostDetail(post),
+      );
+      return;
+    }
+
+    case "public-get": {
+      const post = await context.client.getPublicPostByHandle({
+        publicHandle: requiredPositional(
+          args.positionals,
+          1,
+          "Missing public handle",
+        ),
+        identityName: requiredPositional(
+          args.positionals,
+          2,
+          "Missing public identity name",
+        ),
+        postId: requiredPositional(args.positionals, 3, "Missing post id"),
+      });
+
+      printValue(
+        io,
+        context.outputMode,
+        context.outputMode === "json"
+          ? post
+          : renderPostDetail(post),
+      );
+      return;
+    }
+
+    case "shared-get": {
+      const post = await context.client.getSharedPost(
+        requiredPositional(args.positionals, 1, "Missing share token"),
+      );
+
+      printValue(
+        io,
+        context.outputMode,
+        context.outputMode === "json"
+          ? post
+          : renderPostDetail(post),
+      );
+      return;
+    }
+
+    case "share": {
+      const response = await context.client.sharePost(
+        requiredPositional(args.positionals, 1, "Missing post id"),
+      );
+
+      if (booleanFlag(args.flags, "tokenOnly")) {
+        io.stdout(response.token);
+        return;
+      }
+
+      printValue(
+        io,
+        context.outputMode,
+        context.outputMode === "json"
+          ? response
+          : renderShareToken("Issued post share token", response),
+      );
+      return;
+    }
+
+    case "revoke-share": {
+      const response = await context.client.revokePostShare(
+        requiredPositional(args.positionals, 1, "Missing post id"),
+      );
+
+      printValue(io, context.outputMode, response);
+      return;
+    }
+
+    default:
+      throw new CliError("Unknown post subcommand", 2);
+  }
+}
+
+async function maybeOwnedPostsScope(
+  args: ParsedArgs,
+  context: Awaited<ReturnType<typeof createCommandContext>>,
+  identityId: string,
+): Promise<CacheScope | undefined> {
+  if (!cacheFlags(args).sinceCache && !cacheFlags(args).saveCache) {
+    return undefined;
+  }
+
+  return ownedPostsScope({
+    context,
+    actorKey: await authenticatedActorKey(context),
+    identityId,
+    before: stringFlag(args.flags, "before"),
+    ...payloadFilters(args),
+  });
+}
+
+function maybePublicPostsScope(
+  args: ParsedArgs,
+  context: Awaited<ReturnType<typeof createCommandContext>>,
+  publicHandle: string,
+  identityName: string,
+): CacheScope | undefined {
+  if (!cacheFlags(args).sinceCache && !cacheFlags(args).saveCache) {
+    return undefined;
+  }
+
+  return publicPostsScope({
+    context,
+    publicHandle,
+    identityName,
+    before: stringFlag(args.flags, "before"),
+    ...payloadFilters(args),
+  });
+}
+
+function maybeSharedPostsScope(
+  args: ParsedArgs,
+  context: Awaited<ReturnType<typeof createCommandContext>>,
+  shareToken: string,
+): CacheScope | undefined {
+  if (!cacheFlags(args).sinceCache && !cacheFlags(args).saveCache) {
+    return undefined;
+  }
+
+  return sharedPostsScope({
+    context,
+    shareToken,
+    before: stringFlag(args.flags, "before"),
+    ...payloadFilters(args),
+  });
+}
+
+function renderPostDetail(
+  post: { id: string; attributes: PostAttributes },
+  options: { title?: string; identityId?: string } = {},
+): string {
+  const identityId = options.identityId ?? post.attributes.identity_id;
+
+  return joinBlocks([
+    options.title ?? `Post ${post.id}`,
+    renderFields([
+      ["ID", post.id],
+      ["Identity", renderPostIdentity(post.attributes.identity_name, identityId)],
+      ["Source", post.attributes.source],
+      ["Content", post.attributes.content_format],
+      [
+        "Inserted",
+        post.attributes.inserted_at
+          ? formatTimestamp(post.attributes.inserted_at)
+          : undefined,
+      ],
+      [
+        "Updated",
+        post.attributes.updated_at
+          ? formatTimestamp(post.attributes.updated_at)
+          : undefined,
+      ],
+    ]),
+    post.attributes.body ? "Body\n" + renderBodyBlock(post.attributes.body) : undefined,
+    post.attributes.payload
+      ? "Payload\n" + indent(JSON.stringify(post.attributes.payload, null, 2))
+      : undefined,
+  ]);
+}
+
+function renderPostIdentity(
+  identityName: string | undefined,
+  identityId: string | undefined,
+): string | undefined {
+  if (identityName && identityId) {
+    return `${identityName} (${identityId})`;
+  }
+
+  return identityName ?? identityId;
+}
+
+function renderShareToken(title: string, response: ShareTokenResponse): string {
+  return joinBlocks([
+    title,
+    renderFields([["Token", response.token]]),
+  ]);
+}

package/src/commands/setup.ts

@@ -0,0 +1,228 @@
+import { createInterface } from "node:readline/promises";
+
+import { booleanFlag, stringFlag, type ParsedArgs } from "../lib/args";
+import { ClankmatesClient } from "../lib/client";
+import {
+  loadConfig,
+  resolveBaseUrl,
+  resolveProfileName,
+  updateProfile,
+} from "../lib/config";
+import { CliError } from "../lib/errors";
+import { joinBlocks, renderFields } from "../lib/human";
+import { printValue, type Io } from "../lib/output";
+import { getConfigPath } from "../lib/paths";
+import { readStdin } from "../lib/body-input";
+import type { ProfileConfig, WhoamiResponse, WhoamiUserActor } from "../types/api";
+
+const DEFAULT_SETUP_BASE_URL = "https://clank.id";
+
+export async function runSetupCommand(args: ParsedArgs, io: Io): Promise<void> {
+  const subcommand = args.positionals[0];
+
+  if (subcommand !== "profile") {
+    throw new CliError("Unknown setup subcommand", 2);
+  }
+
+  const configPath = getConfigPath();
+  const config = await loadConfig(configPath);
+  const requestedProfile = stringFlag(args.flags, "profile");
+  const profileName = requestedProfile
+    ? resolveProfileName(config, requestedProfile)
+    : await promptText("Profile name", config.activeProfile);
+  const existingProfile = config.profiles[profileName];
+  const requestedBaseUrl = stringFlag(args.flags, "baseUrl");
+  const baseUrlDefault = existingProfile?.baseUrl ?? DEFAULT_SETUP_BASE_URL;
+  const baseUrl = requestedBaseUrl
+    ? resolveBaseUrl(requestedBaseUrl, baseUrlDefault)
+    : resolveBaseUrl(await promptText("Base URL", baseUrlDefault), baseUrlDefault);
+  const masterToken = await resolveSetupMasterToken(args);
+  const outputMode = booleanFlag(args.flags, "json")
+    ? "json"
+    : (existingProfile?.output ?? "table");
+  const validationProfile: ProfileConfig = {
+    ...(existingProfile ?? { output: "table", identityKeys: {} }),
+    baseUrl,
+  };
+  const client = new ClankmatesClient(validationProfile);
+
+  await client.fetchOpenApi();
+  await client.validateMasterToken(masterToken);
+  const whoami = await client.whoami(masterToken);
+
+  await updateProfile(
+    profileName,
+    (profile, storedConfig) => {
+      profile.baseUrl = baseUrl;
+      profile.masterToken = masterToken;
+      profile.readOnlyToken = undefined;
+      storedConfig.activeProfile = profileName;
+    },
+    configPath,
+  );
+
+  const result = formatSetupProfileResult({
+    profileName,
+    baseUrl,
+    configPath,
+    whoami,
+  });
+
+  printValue(io, outputMode, outputMode === "json" ? result : renderSetupProfileResult(result));
+}
+
+async function resolveSetupMasterToken(args: ParsedArgs): Promise<string> {
+  const flagToken = stringFlag(args.flags, "masterToken");
+
+  if (flagToken) {
+    return flagToken;
+  }
+
+  if (booleanFlag(args.flags, "masterTokenStdin")) {
+    const token = (await readStdin()).trim();
+
+    if (!token) {
+      throw new CliError("No master token read from standard input.", 2);
+    }
+
+    return token;
+  }
+
+  if (process.env.CLANKID_MASTER_TOKEN) {
+    return process.env.CLANKID_MASTER_TOKEN;
+  }
+
+  const token = await promptHidden("Master token");
+
+  if (!token) {
+    throw new CliError("Missing master token.", 2);
+  }
+
+  return token;
+}
+
+async function promptText(label: string, defaultValue: string): Promise<string> {
+  if (!process.stdin.isTTY || !process.stdout.isTTY) {
+    return defaultValue;
+  }
+
+  const rl = createInterface({
+    input: process.stdin,
+    output: process.stdout,
+  });
+
+  try {
+    const answer = await rl.question(`${label} [${defaultValue}]: `);
+    return answer.trim() || defaultValue;
+  } finally {
+    rl.close();
+  }
+}
+
+async function promptHidden(label: string): Promise<string> {
+  if (!process.stdin.isTTY || !process.stdout.isTTY) {
+    throw new CliError(
+      "Missing `--master-token`. Provide `--master-token`, `--master-token-stdin`, or `CLANKID_MASTER_TOKEN` when not running interactively.",
+      2,
+    );
+  }
+
+  const stdin = process.stdin as NodeJS.ReadStream & {
+    setRawMode?: (mode: boolean) => NodeJS.ReadStream;
+  };
+  const chunks: string[] = [];
+
+  process.stdout.write(`${label}: `);
+  stdin.setRawMode?.(true);
+  stdin.resume();
+
+  try {
+    return await new Promise<string>((resolve, reject) => {
+      const onData = (chunk: Buffer) => {
+        const text = chunk.toString("utf8");
+
+        for (const char of text) {
+          if (char === "\u0003") {
+            cleanup();
+            reject(new CliError("Setup cancelled.", 130));
+            return;
+          }
+
+          if (char === "\r" || char === "\n") {
+            cleanup();
+            process.stdout.write("\n");
+            resolve(chunks.join("").trim());
+            return;
+          }
+
+          if (char === "\u007f" || char === "\b") {
+            chunks.pop();
+            continue;
+          }
+
+          chunks.push(char);
+        }
+      };
+
+      const cleanup = () => {
+        stdin.off("data", onData);
+        stdin.setRawMode?.(false);
+      };
+
+      stdin.on("data", onData);
+    });
+  } finally {
+    stdin.setRawMode?.(false);
+  }
+}
+
+function formatSetupProfileResult(input: {
+  profileName: string;
+  baseUrl: string;
+  configPath: string;
+  whoami: WhoamiResponse;
+}) {
+  const actor = userActor(input.whoami);
+
+  return {
+    ok: true,
+    profile: input.profileName,
+    baseUrl: input.baseUrl,
+    configPath: input.configPath,
+    authenticated: input.whoami.authenticated,
+    actorType: actor.type,
+    actorId: actor.id,
+    actorEmail: actor.email,
+    actorScope: actor.scope ?? "master",
+    publicProfilePath: actor.public_profile_path ?? "",
+    nextCommands: [
+      `clank auth whoami --profile ${input.profileName} --json`,
+      `clank doctor --profile ${input.profileName} --json`,
+    ],
+  };
+}
+
+function userActor(whoami: WhoamiResponse): WhoamiUserActor {
+  if (whoami.actor.type !== "user") {
+    throw new CliError("Validated master token resolved to a non-user actor.");
+  }
+
+  return whoami.actor;
+}
+
+function renderSetupProfileResult(
+  result: ReturnType<typeof formatSetupProfileResult>,
+): string {
+  return joinBlocks([
+    renderFields([
+      ["Status", "configured"],
+      ["Profile", result.profile],
+      ["Base URL", result.baseUrl],
+      ["Config", result.configPath],
+      ["Actor", result.actorEmail || result.actorId],
+      ["Scope", result.actorScope],
+      ["Public profile", result.publicProfilePath],
+    ]),
+    "Next commands:\n" + result.nextCommands.map((command) => `  ${command}`).join("\n"),
+  ]);
+}

package/src/commands/skill.ts

@@ -0,0 +1,41 @@
+import { booleanFlag, requiredPositional, stringFlag, type ParsedArgs } from "../lib/args";
+import { CliError } from "../lib/errors";
+import { printValue, type Io } from "../lib/output";
+import { installBundledSkill, resolveSkillHosts, type SkillInstallMode } from "../lib/skills";
+
+export async function runSkillCommand(args: ParsedArgs, io: Io): Promise<void> {
+  const subcommand = requiredPositional(args.positionals, 0, "Missing skill subcommand");
+
+  switch (subcommand) {
+    case "install": {
+      const mode: SkillInstallMode = booleanFlag(args.flags, "copy") ? "copy" : "symlink";
+      const hosts = resolveSkillHosts(stringFlag(args.flags, "host"));
+      const installs = [];
+
+      for (const host of hosts) {
+        installs.push(
+          await installBundledSkill({
+            host,
+            mode,
+            force: booleanFlag(args.flags, "force"),
+          }),
+        );
+      }
+
+      printValue(io, booleanFlag(args.flags, "json") ? "json" : "table", {
+        ok: true,
+        skill: "clankid",
+        installMode: mode,
+        hosts: installs,
+        notes: [
+          "Restart Codex or Claude Code if the new skill does not appear immediately.",
+          "Use --force to replace an existing installed skill target.",
+        ],
+      });
+      return;
+    }
+
+    default:
+      throw new CliError(`Unknown skill subcommand "${subcommand}"`, 2);
+  }
+}

package/src/commands/user.ts

@@ -0,0 +1,33 @@
+import { requiredPositional, type ParsedArgs } from "../lib/args";
+import { createCommandContext } from "../lib/context";
+import { CliError } from "../lib/errors";
+import { printValue, type Io } from "../lib/output";
+
+export async function runUserCommand(args: ParsedArgs, io: Io): Promise<void> {
+  const subcommand = args.positionals[0];
+  const context = await createCommandContext(args, io);
+
+  switch (subcommand) {
+    case "get": {
+      const user = await context.client.getUserByPublicHandle(
+        requiredPositional(args.positionals, 1, "Missing public handle"),
+      );
+
+      printValue(
+        io,
+        context.outputMode,
+        context.outputMode === "json"
+          ? user
+          : {
+              id: user.id,
+              email: user.attributes.email,
+              publicHandle: user.attributes.public_handle ?? "",
+            },
+      );
+      return;
+    }
+
+    default:
+      throw new CliError("Unknown user subcommand", 2);
+  }
+}

package/src/lib/.gitkeep

@@ -0,0 +1 @@
+