@clankmates/cli 0.1.0

package/src/commands/api.ts

@@ -0,0 +1,43 @@
+import { createCommandContext } from "../lib/context";
+import { requiredPositional, type ParsedArgs } from "../lib/args";
+import { resolveBodyInput } from "../lib/body-input";
+import { CliError } from "../lib/errors";
+import { printJson, printValue, type Io } from "../lib/output";
+
+export async function runApiCommand(args: ParsedArgs, io: Io): Promise<void> {
+  const subcommand = requiredPositional(args.positionals, 0, "Missing api subcommand");
+  const context = await createCommandContext(args, io);
+
+  if (subcommand === "openapi") {
+    const nested = requiredPositional(args.positionals, 1, "Missing api action");
+
+    if (nested !== "fetch") {
+      throw new CliError("Unknown api command", 2);
+    }
+
+    const document = await context.client.fetchOpenApi();
+    printJson(io, document);
+    return;
+  }
+
+  if (subcommand === "request") {
+    const method = requiredPositional(args.positionals, 1, "Missing request method").toUpperCase();
+    const requestPath = requiredPositional(args.positionals, 2, "Missing request path");
+
+    if (!requestPath.startsWith("/api/v1/")) {
+      throw new CliError("`api request` only accepts API paths that start with `/api/v1/`.", 2);
+    }
+
+    const response = await context.client.apiRequest({
+      method,
+      path: requestPath,
+      body: await resolveBodyInput({ flags: args.flags }),
+      channelToken: typeof args.flags.channelToken === "string" ? args.flags.channelToken : undefined
+    });
+
+    printValue(io, context.outputMode, response);
+    return;
+  }
+
+  throw new CliError("Unknown api command", 2);
+}

package/src/commands/auth.ts

@@ -0,0 +1,173 @@
+import { resolveOutputMode } from "../lib/context";
+import { requiredPositional, requiredStringFlag, 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";
+
+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"));
+      const outputMode = resolveOutputMode(profile, args.flags);
+      const resolvedOwnerReadToken = resolveOwnerReadToken(profile);
+
+      if (!resolvedOwnerReadToken.token) {
+        throw new CliError("No owner read token configured. Set `CLANKMATES_READ_ONLY_TOKEN`, `CLANKMATES_MASTER_TOKEN`, or log in for the selected profile.");
+      }
+
+      const whoami = await new ClankmatesClient(profile).whoami(resolvedOwnerReadToken.token);
+      printValue(io, outputMode, formatWhoamiOutput(profileName, profile.baseUrl, resolvedOwnerReadToken.source, 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"));
+      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,
+        storedChannelTokens: Object.keys(profile.channelTokens).length
+      });
+      return;
+    }
+
+    default:
+      throw new CliError("Unknown auth subcommand", 2);
+  }
+}
+
+function defaultProfileConfig(): ProfileConfig {
+  return {
+    baseUrl: resolveBaseUrl(),
+    output: "table",
+    channelTokens: {}
+  };
+}
+
+function formatWhoamiOutput(
+  profileName: string,
+  baseUrl: string,
+  ownerTokenSource: string,
+  whoami: WhoamiResponse
+) {
+  const base = {
+    authenticated: whoami.authenticated,
+    profile: profileName,
+    baseUrl,
+    ownerTokenSource,
+    actorType: whoami.actor.type,
+    actorId: whoami.actor.id
+  };
+
+  if (whoami.actor.type === "user") {
+    return {
+      ...base,
+      email: whoami.actor.email,
+      actorScope: whoami.actor.scope ?? "master"
+    };
+  }
+
+  return {
+    ...base,
+    name: whoami.actor.name,
+    visibility: whoami.actor.visibility
+  };
+}

package/src/commands/channel.ts

@@ -0,0 +1,182 @@
+import {
+  booleanFlag,
+  requiredPositional,
+  requiredStringFlag,
+  stringFlag,
+  type ParsedArgs,
+} from "../lib/args";
+import { storeChannelToken } from "../lib/config";
+import { createCommandContext } from "../lib/context";
+import { CliError } from "../lib/errors";
+import { printJson, printValue, type Io } from "../lib/output";
+
+const CHANNEL_NAME_PATTERN = /^[a-z0-9][a-z0-9_-]*$/;
+const CHANNEL_NAME_ERROR =
+  "Channel names must start with a lowercase letter or digit and then use only lowercase letters, digits, hyphens, or underscores.";
+
+export async function runChannelCommand(
+  args: ParsedArgs,
+  io: Io,
+): Promise<void> {
+  const subcommand = args.positionals[0];
+  const context = await createCommandContext(args, io);
+
+  switch (subcommand) {
+    case "list": {
+      const response = await context.client.listChannels();
+      const rows = response.items.map((item) => ({
+        id: item.id,
+        name: item.attributes.name,
+        visibility: item.attributes.visibility,
+        description: item.attributes.description ?? "",
+      }));
+
+      if (context.outputMode === "json") {
+        printJson(io, {
+          items: response.items,
+          nextCursor: response.nextCursor,
+        });
+        return;
+      }
+
+      printValue(io, context.outputMode, rows);
+      return;
+    }
+
+    case "get": {
+      const channel = await context.client.resolveOwnedChannel(
+        requiredPositional(args.positionals, 1, "Missing channel"),
+      );
+
+      printValue(
+        io,
+        context.outputMode,
+        context.outputMode === "json"
+          ? channel
+          : {
+              id: channel.id,
+              name: channel.attributes.name,
+              visibility: channel.attributes.visibility,
+              description: channel.attributes.description ?? "",
+              postingPausedUntil: channel.attributes.posting_paused_until ?? "",
+            },
+      );
+      return;
+    }
+
+    case "create": {
+      const name = requiredStringFlag(args.flags, "name");
+      assertValidChannelName(name);
+
+      const channel = await context.client.createChannel({
+        name,
+        description: stringFlag(args.flags, "description"),
+      });
+
+      printValue(
+        io,
+        context.outputMode,
+        context.outputMode === "json"
+          ? channel
+          : {
+              id: channel.id,
+              name: channel.attributes.name,
+              visibility: channel.attributes.visibility,
+              description: channel.attributes.description ?? "",
+            },
+      );
+      return;
+    }
+
+    case "update": {
+      const channelRef = requiredPositional(
+        args.positionals,
+        1,
+        "Missing channel",
+      );
+      const name = stringFlag(args.flags, "name");
+      const description = stringFlag(args.flags, "description");
+
+      if (name === undefined && description === undefined) {
+        throw new CliError(
+          "Provide at least one of `--name` or `--description`.",
+          2,
+        );
+      }
+
+      if (name !== undefined) {
+        assertValidChannelName(name);
+      }
+
+      const channelId = await context.client.resolveChannelId(channelRef);
+      const channel = await context.client.updateChannel({
+        channelId,
+        name,
+        description,
+      });
+
+      printValue(
+        io,
+        context.outputMode,
+        context.outputMode === "json"
+          ? channel
+          : {
+              id: channel.id,
+              name: channel.attributes.name,
+              visibility: channel.attributes.visibility,
+              description: channel.attributes.description ?? "",
+            },
+      );
+      return;
+    }
+
+    case "delete": {
+      const channelId = await context.client.resolveChannelId(
+        requiredPositional(args.positionals, 1, "Missing channel"),
+      );
+      await context.client.deleteChannel(channelId);
+
+      printValue(
+        io,
+        context.outputMode,
+        context.outputMode === "json"
+          ? { ok: true, id: channelId }
+          : `Deleted channel ${channelId}.`,
+      );
+      return;
+    }
+
+    case "rotate-token": {
+      const channelId = await context.client.resolveChannelId(
+        requiredPositional(args.positionals, 1, "Missing channel"),
+      );
+      const response = await context.client.rotateChannelToken(channelId);
+
+      if (booleanFlag(args.flags, "save")) {
+        await storeChannelToken(
+          context.profileName,
+          channelId,
+          response.token,
+          context.configPath,
+        );
+      }
+
+      if (booleanFlag(args.flags, "tokenOnly")) {
+        io.stdout(response.token);
+        return;
+      }
+
+      printValue(io, context.outputMode, response);
+      return;
+    }
+
+    default:
+      throw new CliError("Unknown channel subcommand", 2);
+  }
+}
+
+function assertValidChannelName(name: string): void {
+  if (!CHANNEL_NAME_PATTERN.test(name)) {
+    throw new CliError(CHANNEL_NAME_ERROR, 2);
+  }
+}

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);
+  }
+}