@clankmates/cli 0.1.0

package/src/commands/doctor.ts

@@ -0,0 +1,265 @@
+import { access } from "node:fs/promises";
+
+import { createCommandContext } from "../lib/context";
+import { channelFlag, type ParsedArgs } from "../lib/args";
+import { printValue, type Io } from "../lib/output";
+import {
+  resolveMasterToken,
+  resolveOwnerReadToken,
+  resolvePublishToken,
+  resolveReadOnlyToken,
+} from "../lib/tokens";
+
+interface DoctorCheck {
+  name: string;
+  ok: boolean;
+  required: boolean;
+  source?: string;
+  detail: string;
+}
+
+export async function runDoctorCommand(
+  args: ParsedArgs,
+  io: Io,
+): Promise<void> {
+  const context = await createCommandContext(args, io);
+  const requestedChannel = channelFlag(args.flags);
+  const resolvedMasterToken = resolveMasterToken(context.profile);
+  const resolvedReadOnlyToken = resolveReadOnlyToken(context.profile);
+  const resolvedOwnerReadToken = resolveOwnerReadToken(context.profile);
+  const configFileExists = await checkConfigPath(context.configPath);
+
+  const channelResolution = requestedChannel
+    ? await resolveRequestedChannel(context, requestedChannel)
+    : { ok: true, channelId: undefined as string | undefined, error: undefined as string | undefined };
+  const resolvedPublishToken = channelResolution.channelId
+    ? resolvePublishToken(context.profile, channelResolution.channelId)
+    : undefined;
+
+  const [
+    openApiCheck,
+    masterTokenCheck,
+    readOnlyTokenCheck,
+    ownerReadTokenCheck,
+  ] = await Promise.all([
+    runCheck(() => context.client.fetchOpenApi()),
+    runOptionalCheck(
+      resolvedMasterToken.token,
+      (token) => context.client.validateMasterToken(token),
+      "No master token configured.",
+    ),
+    runOptionalCheck(
+      resolvedReadOnlyToken.token,
+      (token) => context.client.validateReadOnlyToken(token),
+      "No read-only token configured.",
+    ),
+    runOptionalCheck(
+      resolvedOwnerReadToken.token,
+      (token) => context.client.whoami(token),
+      "No owner-read token configured.",
+    ),
+  ]);
+
+  const checks: DoctorCheck[] = [
+    {
+      name: "config_file",
+      ok: configFileExists,
+      required: false,
+      source: context.configPath,
+      detail: configFileExists
+        ? "Config file exists."
+        : "Config file does not exist yet. Run `clankm config init` to create one.",
+    },
+    {
+      name: "open_api",
+      ok: openApiCheck.ok,
+      required: true,
+      detail: openApiCheck.error ?? "OpenAPI endpoint responded successfully.",
+    },
+    {
+      name: "master_token",
+      ok: masterTokenCheck.ok,
+      required: false,
+      source: resolvedMasterToken.source,
+      detail: masterTokenCheck.error ?? "Master token validated successfully.",
+    },
+    {
+      name: "read_only_token",
+      ok: readOnlyTokenCheck.ok,
+      required: false,
+      source: resolvedReadOnlyToken.source,
+      detail: readOnlyTokenCheck.error ?? "Read-only token validated successfully.",
+    },
+    {
+      name: "owner_read_token",
+      ok: ownerReadTokenCheck.ok,
+      required: false,
+      source: resolvedOwnerReadToken.source,
+      detail:
+        ownerReadTokenCheck.error ??
+        "Owner-read token resolved and validated successfully.",
+    },
+  ];
+
+  if (requestedChannel) {
+    checks.push({
+      name: "channel_resolution",
+      ok: channelResolution.ok,
+      required: false,
+      source: requestedChannel,
+      detail:
+        channelResolution.error ??
+        `Resolved requested channel to ${channelResolution.channelId}.`,
+    });
+    checks.push({
+      name: "publish_token",
+      ok: Boolean(resolvedPublishToken?.token),
+      required: false,
+      source: resolvedPublishToken?.source ?? "none",
+      detail: resolvedPublishToken?.token
+        ? "A publish-capable token is available for the requested channel."
+        : "No publish-capable token is available for the requested channel.",
+    });
+  }
+
+  const publishReady = requestedChannel
+    ? channelResolution.ok && Boolean(resolvedPublishToken?.token)
+    : false;
+  const ownerReadReady = ownerReadTokenCheck.ok;
+  const ok = openApiCheck.ok && ownerReadReady && (!requestedChannel || publishReady);
+  const suggestions = buildSuggestions({
+    configFileExists,
+    openApiOk: openApiCheck.ok,
+    ownerReadReady,
+    requestedChannel,
+    channelResolutionOk: channelResolution.ok,
+    publishReady,
+  });
+
+  printValue(io, context.outputMode, {
+    ok,
+    status: ok ? "ok" : "needs_attention",
+    summary: ok
+      ? requestedChannel
+        ? "CLI can reach the API and publish to the requested channel."
+        : "CLI can reach the API."
+      : requestedChannel
+        ? "CLI setup needs attention before publish workflows are reliable."
+        : "CLI setup needs attention before agent workflows are reliable.",
+    profile: context.profileName,
+    configPath: context.configPath,
+    configFileExists,
+    baseUrl: context.profile.baseUrl,
+    hasMasterToken: Boolean(resolvedMasterToken.token),
+    masterTokenSource: resolvedMasterToken.source,
+    masterTokenOk: masterTokenCheck.ok,
+    masterTokenError: masterTokenCheck.error ?? "",
+    hasReadOnlyToken: Boolean(resolvedReadOnlyToken.token),
+    readOnlyTokenSource: resolvedReadOnlyToken.source,
+    readOnlyTokenOk: readOnlyTokenCheck.ok,
+    readOnlyTokenError: readOnlyTokenCheck.error ?? "",
+    ownerReadTokenAvailable: Boolean(resolvedOwnerReadToken.token),
+    ownerReadTokenSource: resolvedOwnerReadToken.source,
+    ownerReadTokenOk: ownerReadTokenCheck.ok,
+    ownerReadTokenError: ownerReadTokenCheck.error ?? "",
+    ownerReadReady,
+    openApiOk: openApiCheck.ok,
+    openApiError: openApiCheck.error ?? "",
+    storedChannelTokens: Object.keys(context.profile.channelTokens).length,
+    channel: requestedChannel ?? "",
+    channelId: channelResolution.channelId ?? "",
+    channelResolutionOk: channelResolution.ok,
+    channelResolutionError: channelResolution.error ?? "",
+    publishTokenAvailable: Boolean(resolvedPublishToken?.token),
+    publishTokenSource: resolvedPublishToken?.source ?? "none",
+    publishReady,
+    checks,
+    suggestions,
+  });
+}
+
+async function checkConfigPath(configPath: string): Promise<boolean> {
+  try {
+    await access(configPath);
+    return true;
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") {
+      return false;
+    }
+
+    return false;
+  }
+}
+
+async function resolveRequestedChannel(
+  context: Awaited<ReturnType<typeof createCommandContext>>,
+  channel: string,
+): Promise<{ ok: boolean; channelId?: string; error?: string }> {
+  try {
+    return {
+      ok: true,
+      channelId: await context.client.resolveChannelId(channel),
+    };
+  } catch (error) {
+    return {
+      ok: false,
+      error: (error as Error).message,
+    };
+  }
+}
+
+async function runOptionalCheck(
+  token: string | undefined,
+  operation: (token: string) => Promise<unknown>,
+  missingMessage: string,
+): Promise<{ ok: boolean; error?: string }> {
+  if (!token) {
+    return { ok: false, error: missingMessage };
+  }
+
+  return runCheck(() => operation(token));
+}
+
+async function runCheck(
+  operation: () => Promise<unknown>,
+): Promise<{ ok: boolean; error?: string }> {
+  try {
+    await operation();
+    return { ok: true };
+  } catch (error) {
+    return { ok: false, error: (error as Error).message };
+  }
+}
+
+function buildSuggestions(input: {
+  configFileExists: boolean;
+  openApiOk: boolean;
+  ownerReadReady: boolean;
+  requestedChannel?: string;
+  channelResolutionOk: boolean;
+  publishReady: boolean;
+}): string[] {
+  const suggestions: string[] = [];
+
+  if (!input.configFileExists) {
+    suggestions.push("Run `clankm config init` to create local config.");
+  }
+
+  if (!input.openApiOk) {
+    suggestions.push("Check `CLANKMATES_BASE_URL` or `--base-url`, then retry `clankm doctor --json`.");
+  }
+
+  if (!input.ownerReadReady) {
+    suggestions.push("Configure a read-only or master token for owner reads with `clankm auth login ...`.");
+  }
+
+  if (input.requestedChannel && !input.channelResolutionOk) {
+    suggestions.push("Use a channel UUID or configure an owner-read token so channel names can be resolved.");
+  }
+
+  if (input.requestedChannel && !input.publishReady) {
+    suggestions.push("Provide `--channel-token`, `CLANKMATES_CHANNEL_TOKEN`, `CLANKMATES_CHANNEL_TOKENS_JSON`, `CLANKMATES_CHANNEL_TOKENS_FILE`, or a master token for publish.");
+  }
+
+  return suggestions;
+}

package/src/commands/feed.ts

@@ -0,0 +1,46 @@
+import {
+  channelFlag,
+  integerFlag,
+  stringFlag,
+  type ParsedArgs,
+} from "../lib/args";
+import { createCommandContext } from "../lib/context";
+import { CliError } from "../lib/errors";
+import { printJson, printValue, type Io } from "../lib/output";
+
+export async function runFeedCommand(args: ParsedArgs, io: Io): Promise<void> {
+  const subcommand = args.positionals[0];
+
+  if (subcommand !== "my") {
+    throw new CliError("Unknown feed subcommand", 2);
+  }
+
+  const context = await createCommandContext(args, io);
+  const channel = channelFlag(args.flags);
+  const response = await context.client.myFeed({
+    channelId: channel
+      ? await context.client.resolveChannelId(channel)
+      : undefined,
+    limit: integerFlag(args.flags, "limit", { label: "--limit" }),
+    cursor: stringFlag(args.flags, "cursor"),
+  });
+
+  if (context.outputMode === "json") {
+    printJson(io, {
+      items: response.items,
+      nextCursor: response.nextCursor,
+    });
+    return;
+  }
+
+  printValue(
+    io,
+    context.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,
+    })),
+  );
+}

package/src/commands/post.ts

@@ -0,0 +1,140 @@
+import {
+  integerFlag,
+  requiredChannelFlag,
+  requiredPositional,
+  stringFlag,
+  type ParsedArgs,
+} from "../lib/args";
+import { resolveBodyInput } from "../lib/body-input";
+import { createCommandContext } from "../lib/context";
+import { CliError } from "../lib/errors";
+import { printJson, printValue, type Io } from "../lib/output";
+
+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 channelId = await context.client.resolveChannelId(
+        requiredChannelFlag(args.flags),
+      );
+      const body = await resolveBodyInput({
+        flags: args.flags,
+        requireBody: true,
+      });
+      const post = await context.client.publishPost({
+        channelId,
+        body: body!,
+        channelToken: stringFlag(args.flags, "channelToken"),
+      });
+
+      printValue(
+        io,
+        context.outputMode,
+        context.outputMode === "json"
+          ? post
+          : {
+              id: post.id,
+              channelId,
+              source: post.attributes.source,
+              body: post.attributes.body,
+            },
+      );
+      return;
+    }
+
+    case "list": {
+      const response = await context.client.listChannelPosts({
+        channelId: await context.client.resolveChannelId(
+          requiredChannelFlag(args.flags),
+        ),
+        limit: integerFlag(args.flags, "limit", { label: "--limit" }),
+        cursor: stringFlag(args.flags, "cursor"),
+      });
+
+      if (context.outputMode === "json") {
+        printJson(io, {
+          items: response.items,
+          nextCursor: response.nextCursor,
+        });
+        return;
+      }
+
+      printValue(
+        io,
+        context.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,
+        })),
+      );
+      return;
+    }
+
+    case "edit": {
+      const post = await context.client.editPost({
+        postId: requiredPositional(args.positionals, 1, "Missing post id"),
+        body: (await resolveBodyInput({
+          flags: args.flags,
+          requireBody: true,
+        }))!,
+        channelToken: stringFlag(args.flags, "channelToken"),
+      });
+
+      printValue(
+        io,
+        context.outputMode,
+        context.outputMode === "json"
+          ? post
+          : {
+              id: post.id,
+              source: post.attributes.source,
+              body: post.attributes.body,
+            },
+      );
+      return;
+    }
+
+    case "delete": {
+      const postId = requiredPositional(args.positionals, 1, "Missing post id");
+      await context.client.deletePost({
+        postId,
+        channelToken: stringFlag(args.flags, "channelToken"),
+      });
+
+      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
+          : {
+              id: post.id,
+              source: post.attributes.source,
+              body: post.attributes.body,
+            },
+      );
+      return;
+    }
+
+    default:
+      throw new CliError("Unknown post subcommand", 2);
+  }
+}

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: "clankmates",
+        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/lib/.gitkeep

@@ -0,0 +1 @@
+

package/src/lib/args.ts

@@ -0,0 +1,163 @@
+import { parseArgs as parseNodeArgs } from "node:util";
+
+import { CliError } from "./errors";
+
+const CLI_OPTIONS = {
+  help: { type: "boolean", short: "h" },
+  json: { type: "boolean" },
+  profile: { type: "string" },
+  baseUrl: { type: "string" },
+  "base-url": { type: "string" },
+  output: { type: "string" },
+  host: { type: "string" },
+  masterToken: { type: "string" },
+  "master-token": { type: "string" },
+  readOnlyToken: { type: "string" },
+  "read-only-token": { type: "string" },
+  name: { type: "string" },
+  description: { type: "string" },
+  save: { type: "boolean" },
+  force: { type: "boolean" },
+  copy: { type: "boolean" },
+  tokenOnly: { type: "boolean" },
+  "token-only": { type: "boolean" },
+  channel: { type: "string" },
+  "channel-id": { type: "string" },
+  channelToken: { type: "string" },
+  "channel-token": { type: "string" },
+  body: { type: "string" },
+  bodyFile: { type: "string" },
+  "body-file": { type: "string" },
+  stdin: { type: "boolean" },
+  limit: { type: "string" },
+  cursor: { type: "string" },
+} as const;
+
+type ParsedValue = string | boolean;
+
+export interface ParsedArgs {
+  commandPath: string[];
+  positionals: string[];
+  flags: Record<string, ParsedValue>;
+}
+
+export function parseArgs(argv: string[]): ParsedArgs {
+  const parsed = parseNodeArgs({
+    args: argv,
+    allowPositionals: true,
+    strict: false,
+    options: CLI_OPTIONS,
+  });
+  const [command, ...positionals] = parsed.positionals;
+
+  return {
+    commandPath: command ? [command] : [],
+    positionals,
+    flags: normalizeFlags(
+      parsed.values as Record<string, ParsedValue | undefined>,
+    ),
+  };
+}
+
+export function stringFlag(
+  flags: ParsedArgs["flags"],
+  key: string,
+): string | undefined {
+  const value = flags[key];
+  return typeof value === "string" ? value : undefined;
+}
+
+export function requiredStringFlag(
+  flags: ParsedArgs["flags"],
+  key: string,
+): string {
+  const value = stringFlag(flags, key);
+
+  if (!value) {
+    throw new CliError(`Missing \`${toFlagName(key)}\``, 2);
+  }
+
+  return value;
+}
+
+export function channelFlag(flags: ParsedArgs["flags"]): string | undefined {
+  return stringFlag(flags, "channel") ?? stringFlag(flags, "channelId");
+}
+
+export function requiredChannelFlag(flags: ParsedArgs["flags"]): string {
+  const value = channelFlag(flags);
+
+  if (!value) {
+    throw new CliError("Missing `--channel`", 2);
+  }
+
+  return value;
+}
+
+export function integerFlag(
+  flags: ParsedArgs["flags"],
+  key: string,
+  options: { min?: number; label?: string } = {},
+): number | undefined {
+  const value = stringFlag(flags, key);
+
+  if (!value) {
+    return undefined;
+  }
+
+  const parsed = Number.parseInt(value, 10);
+  const minimum = options.min ?? 1;
+
+  if (!Number.isFinite(parsed) || parsed < minimum) {
+    throw new CliError(
+      `${options.label ?? toFlagName(key)} must be an integer >= ${minimum}`,
+      2,
+    );
+  }
+
+  return parsed;
+}
+
+export function booleanFlag(flags: ParsedArgs["flags"], key: string): boolean {
+  return flags[key] === true;
+}
+
+export function requiredPositional(
+  positionals: string[],
+  index: number,
+  message: string,
+): string {
+  const value = positionals[index];
+
+  if (!value) {
+    throw new CliError(message, 2);
+  }
+
+  return value;
+}
+
+function normalizeFlags(
+  values: Record<string, ParsedValue | undefined>,
+): Record<string, ParsedValue> {
+  const flags: Record<string, ParsedValue> = {};
+
+  for (const [key, value] of Object.entries(values)) {
+    if (value === undefined) {
+      continue;
+    }
+
+    flags[toCamelCase(key)] = value;
+  }
+
+  return flags;
+}
+
+function toCamelCase(value: string): string {
+  return value.replace(/-([a-z])/g, (_, letter: string) =>
+    letter.toUpperCase(),
+  );
+}
+
+function toFlagName(value: string): string {
+  return `--${value.replace(/[A-Z]/g, (letter) => `-${letter.toLowerCase()}`)}`;
+}