@clankid/cli 0.17.0

package/src/commands/auth/access-keys.ts

@@ -0,0 +1,206 @@
+import {
+  booleanFlag,
+  requiredPositional,
+  requiredStringFlag,
+  stringFlag,
+  type ParsedArgs,
+} from "../../lib/args";
+import { resolveOutputMode } from "../../lib/context";
+import { loadConfig, resolveProfile, updateProfile } from "../../lib/config";
+import { ClankmatesClient } from "../../lib/client";
+import { CliError } from "../../lib/errors";
+import { joinBlocks, renderFields, renderTokenAction } from "../../lib/human";
+import { printJson, printValue, type Io } from "../../lib/output";
+import { getConfigPath } from "../../lib/paths";
+import type {
+  AccessKeyAttributes,
+  AccessKeyIssueResponse,
+  AccessKeyRevokeResponse,
+  AccessKeyScope,
+  ProfileConfig,
+} from "../../types/api";
+
+export async function runAccessKeyCommand(
+  args: ParsedArgs,
+  config: Awaited<ReturnType<typeof loadConfig>>,
+  io: Io,
+): Promise<void> {
+  const keyCommand = requiredPositional(
+    args.positionals,
+    1,
+    "Missing auth key subcommand",
+  );
+  const { profileName, profile } = resolveProfile(
+    config,
+    stringFlag(args.flags, "profile"),
+    stringFlag(args.flags, "baseUrl"),
+  );
+  const outputMode = resolveOutputMode(profile, args.flags);
+  const client = new ClankmatesClient(profile);
+  const configPath = getConfigPath();
+
+  switch (keyCommand) {
+    case "list": {
+      const scope = parseAccessKeyScope(stringFlag(args.flags, "scope"), false);
+      const response = await client.listAccessKeys(scope);
+
+      if (outputMode === "json") {
+        printJson(io, { items: response.items });
+        return;
+      }
+
+      printValue(
+        io,
+        outputMode,
+        response.items.map((item) => formatAccessKeyRow(item)),
+      );
+      return;
+    }
+
+    case "issue": {
+      const scope = requireAccessKeyScope(
+        requiredStringFlag(args.flags, "scope"),
+      );
+      const response = await client.issueAccessKey({
+        scope,
+        name: requiredStringFlag(args.flags, "name"),
+      });
+
+      if (booleanFlag(args.flags, "tokenOnly")) {
+        io.stdout(response.token);
+        return;
+      }
+
+      printValue(
+        io,
+        outputMode,
+        outputMode === "json"
+          ? response
+          : renderAccessKeyIssue("Issued owner access key", response),
+      );
+      return;
+    }
+
+    case "revoke": {
+      const response = await client.revokeAccessKey(
+        requiredPositional(args.positionals, 2, "Missing access key id"),
+      );
+      await pruneInvalidStoredOwnerTokens(
+        profileName,
+        profile,
+        client,
+        configPath,
+      );
+      printValue(
+        io,
+        outputMode,
+        outputMode === "json"
+          ? response
+          : renderAccessKeyRevoke("Revoked owner access key", response),
+      );
+      return;
+    }
+
+    default:
+      throw new CliError("Unknown auth key subcommand", 2);
+  }
+}
+
+function parseAccessKeyScope(
+  scope: string | undefined,
+  required: boolean,
+): AccessKeyScope | undefined {
+  if (scope === undefined) {
+    if (required) {
+      throw new CliError("Missing `--scope`", 2);
+    }
+
+    return undefined;
+  }
+
+  if (scope !== "master" && scope !== "read_only") {
+    throw new CliError("`--scope` must be either `master` or `read_only`.", 2);
+  }
+
+  return scope;
+}
+
+function requireAccessKeyScope(scope: string): AccessKeyScope {
+  const parsed = parseAccessKeyScope(scope, true);
+
+  if (!parsed) {
+    throw new CliError("Missing `--scope`", 2);
+  }
+
+  return parsed;
+}
+
+function formatAccessKeyRow(item: { id: string; attributes: AccessKeyAttributes }) {
+  return {
+    id: item.id,
+    scope: item.attributes.scope,
+    name: item.attributes.name ?? "",
+    expiresAt: item.attributes.expires_at,
+    issuedAt: item.attributes.inserted_at ?? "",
+  };
+}
+
+function renderAccessKeyIssue(
+  title: string,
+  response: AccessKeyIssueResponse,
+): string {
+  return renderTokenAction({
+    title,
+    id: response.id,
+    name: response.name,
+    token: response.token,
+    issuedAt: response.issued_at,
+    expiresAt: response.expires_at,
+  });
+}
+
+function renderAccessKeyRevoke(
+  title: string,
+  response: AccessKeyRevokeResponse,
+): string {
+  return joinBlocks([
+    title,
+    renderFields([
+      ["ID", response.id],
+      ["Scope", response.scope],
+      ["Name", response.name],
+    ]),
+  ]);
+}
+
+async function pruneInvalidStoredOwnerTokens(
+  profileName: string,
+  profile: ProfileConfig,
+  client: ClankmatesClient,
+  configPath: string,
+): Promise<void> {
+  const invalidMasterToken = profile.masterToken
+    ? !(await client.canAuthenticate(profile.masterToken))
+    : false;
+  const invalidReadOnlyToken = profile.readOnlyToken
+    ? !(await client.canAuthenticate(profile.readOnlyToken))
+    : false;
+
+  if (!invalidMasterToken && !invalidReadOnlyToken) {
+    return;
+  }
+
+  await updateProfile(
+    profileName,
+    (storedProfile) => {
+      if (invalidMasterToken) {
+        storedProfile.masterToken = undefined;
+      }
+
+      if (invalidReadOnlyToken) {
+        storedProfile.readOnlyToken = undefined;
+      }
+    },
+    configPath,
+  );
+}

package/src/commands/auth.ts

@@ -0,0 +1,240 @@
+import { resolveOutputMode } from "../lib/context";
+import {
+  booleanFlag,
+  requiredPositional,
+  stringFlag,
+  type ParsedArgs,
+} from "../lib/args";
+import {
+  loadConfig,
+  resolveBaseUrl,
+  resolveProfile,
+  resolveProfileName,
+  updateProfile,
+} from "../lib/config";
+import { ClankmatesClient } from "../lib/client";
+import { CliError } from "../lib/errors";
+import { printValue, type Io } from "../lib/output";
+import { getConfigPath } from "../lib/paths";
+import {
+  resolveMasterToken,
+  resolveOwnerReadToken,
+  resolveReadOnlyToken,
+} from "../lib/tokens";
+import type { ProfileConfig, WhoamiResponse } from "../types/api";
+import { runAccessKeyCommand } from "./auth/access-keys";
+
+export async function runAuthCommand(args: ParsedArgs, io: Io): Promise<void> {
+  const subcommand = args.positionals[0];
+  const configPath = getConfigPath();
+  const config = await loadConfig(configPath);
+
+  switch (subcommand) {
+    case "login": {
+      const requestedProfile = stringFlag(args.flags, "profile");
+      const profileName = resolveProfileName(config, requestedProfile);
+      const profile = config.profiles[profileName] ?? defaultProfileConfig();
+      const outputMode = resolveOutputMode(profile, args.flags);
+      const masterToken = stringFlag(args.flags, "masterToken");
+      const readOnlyToken = stringFlag(args.flags, "readOnlyToken");
+      const baseUrl = stringFlag(args.flags, "baseUrl");
+      const resolvedBaseUrl = resolveBaseUrl(baseUrl, profile.baseUrl);
+      const validationProfile = {
+        ...profile,
+        baseUrl: resolvedBaseUrl,
+      };
+
+      if (Boolean(masterToken) === Boolean(readOnlyToken)) {
+        throw new CliError(
+          "Provide exactly one of `--master-token` or `--read-only-token`.",
+        );
+      }
+
+      const client = new ClankmatesClient(validationProfile);
+
+      if (masterToken) {
+        await client.validateMasterToken(masterToken);
+      } else if (readOnlyToken) {
+        await client.validateReadOnlyToken(readOnlyToken);
+      }
+
+      await updateProfile(
+        profileName,
+        (storedProfile) => {
+          if (masterToken) {
+            storedProfile.masterToken = masterToken;
+            storedProfile.readOnlyToken = undefined;
+          }
+
+          if (readOnlyToken) {
+            storedProfile.readOnlyToken = readOnlyToken;
+          }
+
+          if (baseUrl) {
+            storedProfile.baseUrl = baseUrl;
+          }
+        },
+        configPath,
+      );
+
+      printValue(io, outputMode, {
+        authenticated: true,
+        profile: profileName,
+        baseUrl: resolvedBaseUrl,
+        tokenKind: masterToken ? "master" : "read_only",
+      });
+      return;
+    }
+
+    case "whoami": {
+      const { profileName, profile } = resolveProfile(
+        config,
+        stringFlag(args.flags, "profile"),
+        stringFlag(args.flags, "baseUrl"),
+      );
+      const outputMode = resolveOutputMode(profile, args.flags);
+      const explicitIdentityKey = stringFlag(args.flags, "identityKey");
+      const resolvedOwnerReadToken = resolveOwnerReadToken(profile);
+      const resolvedToken = explicitIdentityKey
+        ? {
+            token: explicitIdentityKey,
+            source: "flag",
+            tokenKind: "identity" as const,
+          }
+        : {
+            token: resolvedOwnerReadToken.token,
+            source: resolvedOwnerReadToken.source,
+            tokenKind: "owner_read" as const,
+          };
+
+      if (!resolvedToken.token) {
+        throw new CliError(
+          "No token configured for `auth whoami`. Provide `--identity-key`, set `CLANKID_READ_ONLY_TOKEN`, `CLANKID_MASTER_TOKEN`, or log in for the selected profile.",
+        );
+      }
+
+      const whoami = await new ClankmatesClient(profile).whoami(
+        resolvedToken.token,
+      );
+
+      printValue(
+        io,
+        outputMode,
+        formatWhoamiOutput(profileName, profile.baseUrl, resolvedToken, whoami),
+      );
+      return;
+    }
+
+    case "logout": {
+      const { profileName } = resolveProfile(
+        config,
+        stringFlag(args.flags, "profile"),
+      );
+      await updateProfile(
+        profileName,
+        (profile) => {
+          profile.masterToken = undefined;
+          profile.readOnlyToken = undefined;
+        },
+        configPath,
+      );
+      io.stdout(`Cleared owner tokens for profile ${profileName}`);
+      return;
+    }
+
+    case "token": {
+      const tokenCommand = requiredPositional(
+        args.positionals,
+        1,
+        "Missing auth token subcommand",
+      );
+
+      if (tokenCommand !== "inspect") {
+        throw new CliError("Unknown auth token subcommand", 2);
+      }
+
+      const { profileName, profile } = resolveProfile(
+        config,
+        stringFlag(args.flags, "profile"),
+        stringFlag(args.flags, "baseUrl"),
+      );
+      const outputMode = resolveOutputMode(profile, args.flags);
+      const resolvedMasterToken = resolveMasterToken(profile);
+      const resolvedReadOnlyToken = resolveReadOnlyToken(profile);
+      const resolvedOwnerReadToken = resolveOwnerReadToken(profile);
+
+      printValue(io, outputMode, {
+        profile: profileName,
+        baseUrl: profile.baseUrl,
+        hasMasterToken: Boolean(resolvedMasterToken.token),
+        masterTokenSource: resolvedMasterToken.source,
+        hasReadOnlyToken: Boolean(resolvedReadOnlyToken.token),
+        readOnlyTokenSource: resolvedReadOnlyToken.source,
+        ownerReadTokenAvailable: Boolean(resolvedOwnerReadToken.token),
+        ownerReadTokenSource: resolvedOwnerReadToken.source,
+        storedIdentityKeys: Object.keys(profile.identityKeys).length,
+      });
+      return;
+    }
+
+    case "key":
+    case "access-key": {
+      await runAccessKeyCommand(args, config, io);
+      return;
+    }
+
+    default:
+      throw new CliError("Unknown auth subcommand", 2);
+  }
+}
+
+function defaultProfileConfig(): ProfileConfig {
+  return {
+    baseUrl: resolveBaseUrl(),
+    output: "table",
+    identityKeys: {},
+  };
+}
+
+function formatWhoamiOutput(
+  profileName: string,
+  baseUrl: string,
+  resolvedToken: { source: string; tokenKind: "owner_read" | "identity" },
+  whoami: WhoamiResponse,
+) {
+  const base = {
+    authenticated: whoami.authenticated,
+    profile: profileName,
+    baseUrl,
+    tokenKind: resolvedToken.tokenKind,
+    tokenSource: resolvedToken.source,
+    ownerTokenSource:
+      resolvedToken.tokenKind === "owner_read" ? resolvedToken.source : undefined,
+    actorType: whoami.actor.type,
+    actorId: whoami.actor.id,
+  };
+
+  if (whoami.actor.type === "user") {
+    return {
+      ...base,
+      email: whoami.actor.email,
+      actorScope: whoami.actor.scope ?? "master",
+      authenticatedVia: whoami.actor.authenticated_via ?? "",
+      publicHandle: whoami.actor.public_handle ?? "",
+      publicProfilePath: whoami.actor.public_profile_path ?? "",
+      publicProfileUrl: whoami.actor.public_profile_url ?? "",
+    };
+  }
+
+  return {
+    ...base,
+    name: whoami.actor.name,
+    visibility: whoami.actor.visibility,
+    publiclyListed: whoami.actor.publicly_listed ?? false,
+    postingPausedUntil: whoami.actor.posting_paused_until ?? "",
+    ownerId: whoami.actor.owner_id ?? "",
+    ownerPublicHandle: whoami.actor.owner_public_handle ?? "",
+    publicPath: whoami.actor.public_path ?? "",
+    publicUrl: whoami.actor.public_url ?? "",
+  };
+}

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/config.ts

@@ -0,0 +1,93 @@
+import {
+  ensureConfig,
+  ensureProfile,
+  loadConfig,
+  resolveProfile,
+  resolveProfileName,
+  setActiveProfile,
+  setProfileBaseUrl,
+  setProfileOutput
+} from "../lib/config";
+import { booleanFlag, requiredPositional, stringFlag, type ParsedArgs } from "../lib/args";
+import { CliError } from "../lib/errors";
+import { printValue, type Io } from "../lib/output";
+import { getConfigPath } from "../lib/paths";
+
+export async function runConfigCommand(args: ParsedArgs, io: Io): Promise<void> {
+  const subcommand = requiredPositional(args.positionals, 0, "Missing config subcommand");
+  const configPath = getConfigPath();
+
+  switch (subcommand) {
+    case "init": {
+      const baseUrl = stringFlag(args.flags, "baseUrl");
+      const requestedProfile = stringFlag(args.flags, "profile");
+      const config = requestedProfile
+        ? await ensureProfile(resolveProfileName(await loadConfig(configPath), requestedProfile), configPath, baseUrl)
+        : await ensureConfig(configPath, baseUrl);
+      const { profileName, profile } = resolveProfile(config, requestedProfile);
+
+      printValue(io, booleanFlag(args.flags, "json") ? "json" : "table", {
+        configPath,
+        profile: profileName,
+        activeProfile: config.activeProfile,
+        baseUrl: profile.baseUrl,
+        output: profile.output
+      });
+      return;
+    }
+
+    case "set": {
+      const key = requiredPositional(args.positionals, 1, "Missing config key");
+      const value = requiredPositional(args.positionals, 2, "Missing config value");
+      const config = await loadConfig(configPath);
+      const { profileName } = resolveProfile(config, stringFlag(args.flags, "profile"));
+
+      if (key === "base-url") {
+        await setProfileBaseUrl(profileName, value, configPath);
+        io.stdout(`Set base URL for profile ${profileName} to ${value}`);
+        return;
+      }
+
+      if (key === "output") {
+        if (value !== "json" && value !== "table") {
+          throw new CliError("Output must be `json` or `table`", 2);
+        }
+
+        await setProfileOutput(profileName, value, configPath);
+        io.stdout(`Set output for profile ${profileName} to ${value}`);
+        return;
+      }
+
+      throw new CliError(`Unknown config key "${key}"`, 2);
+    }
+
+    case "profile": {
+      const profileCommand = requiredPositional(args.positionals, 1, "Missing profile subcommand");
+
+      if (profileCommand === "list") {
+        const config = await loadConfig(configPath);
+        const rows = Object.entries(config.profiles).map(([name, profile]) => ({
+          name,
+          active: name === config.activeProfile ? "yes" : "",
+          baseUrl: profile.baseUrl,
+          output: profile.output
+        }));
+
+        printValue(io, booleanFlag(args.flags, "json") ? "json" : "table", rows);
+        return;
+      }
+
+      if (profileCommand === "use") {
+        const name = requiredPositional(args.positionals, 2, "Missing profile name");
+        const config = await setActiveProfile(name, configPath);
+        io.stdout(`Active profile is now ${config.activeProfile}`);
+        return;
+      }
+
+      throw new CliError(`Unknown profile subcommand "${profileCommand}"`, 2);
+    }
+
+    default:
+      throw new CliError(`Unknown config subcommand "${subcommand}"`, 2);
+  }
+}