@clankid/cli 0.17.0

package/src/commands/doctor/checks.ts

@@ -0,0 +1,123 @@
+import { access } from "node:fs/promises";
+
+import type {
+  IdentityDiagnostics,
+  IdentityDiagnosticsResult,
+  IdentityResolution,
+  CheckResult,
+  DoctorContext,
+} from "./types";
+
+export 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;
+  }
+}
+
+export async function resolveRequestedIdentity(
+  context: DoctorContext,
+  identity: string,
+): Promise<IdentityResolution> {
+  try {
+    return {
+      ok: true,
+      identityId: await context.client.resolveIdentityId(identity),
+    };
+  } catch (error) {
+    return {
+      ok: false,
+      error: (error as Error).message,
+    };
+  }
+}
+
+export async function runOptionalCheck(
+  token: string | undefined,
+  operation: (token: string) => Promise<unknown>,
+  missingMessage: string,
+): Promise<CheckResult> {
+  if (!token) {
+    return { ok: false, error: missingMessage };
+  }
+
+  return runCheck(() => operation(token));
+}
+
+export async function runCheck(
+  operation: () => Promise<unknown>,
+): Promise<CheckResult> {
+  try {
+    await operation();
+    return { ok: true };
+  } catch (error) {
+    return { ok: false, error: (error as Error).message };
+  }
+}
+
+export async function maybeFetchIdentityDiagnostics(input: {
+  context: DoctorContext;
+  requestedIdentity?: string;
+  identityResolution: IdentityResolution;
+  ownerReadReady: boolean;
+}): Promise<IdentityDiagnosticsResult> {
+  if (!input.requestedIdentity) {
+    return { ok: false };
+  }
+
+  if (!input.identityResolution.ok || !input.identityResolution.identityId) {
+    return {
+      ok: false,
+      error: "Identity diagnostics require a resolved identity.",
+    };
+  }
+
+  if (!input.ownerReadReady) {
+    return {
+      ok: false,
+      error: "Identity diagnostics require an owner-read token.",
+    };
+  }
+
+  try {
+    return {
+      ok: true,
+      value: await input.context.client.getIdentityDiagnostics(
+        input.identityResolution.identityId,
+      ),
+    };
+  } catch (error) {
+    return {
+      ok: false,
+      error: (error as Error).message,
+    };
+  }
+}
+
+export function formatIdentitySummary(
+  diagnostics: IdentityDiagnostics | undefined,
+): string {
+  if (!diagnostics || diagnostics.state_labels.length === 0) {
+    return "";
+  }
+
+  return diagnostics.state_labels.join(", ");
+}
+
+export function formatIdentityDiagnosticsDetail(
+  diagnostics: IdentityDiagnostics | undefined,
+): string {
+  const summary = formatIdentitySummary(diagnostics);
+
+  if (!summary) {
+    return "Identity diagnostics are unavailable.";
+  }
+
+  return `Identity diagnostics loaded successfully: ${summary}.`;
+}

package/src/commands/doctor/render.ts

@@ -0,0 +1,140 @@
+import {
+  formatTimestamp,
+  joinBlocks,
+  renderBullets,
+  renderFields,
+  renderSection,
+} from "../../lib/human";
+import type { DoctorCheck, DoctorReport } from "./types";
+
+export function renderDoctorReport(report: DoctorReport): string {
+  return joinBlocks([
+    renderSection(
+      "Status",
+      renderFields([
+        ["Result", report.status],
+        ["Summary", report.summary],
+        ["Profile", report.profile],
+        ["Base URL", report.baseUrl],
+        ["Config", report.configPath],
+        ["CLI version", report.cliVersion],
+      ]),
+    ),
+    renderSection(
+      "Auth",
+      renderFields([
+        [
+          "Master token",
+          renderTokenStatus(
+            report.hasMasterToken,
+            report.masterTokenOk,
+            report.masterTokenSource,
+            report.masterTokenError,
+          ),
+        ],
+        [
+          "Read-only token",
+          renderTokenStatus(
+            report.hasReadOnlyToken,
+            report.readOnlyTokenOk,
+            report.readOnlyTokenSource,
+            report.readOnlyTokenError,
+          ),
+        ],
+        [
+          "Owner-read token",
+          renderTokenStatus(
+            report.ownerReadTokenAvailable,
+            report.ownerReadTokenOk,
+            report.ownerReadTokenSource,
+            report.ownerReadTokenError,
+          ),
+        ],
+        ["Stored identity keys", report.storedIdentityKeys],
+      ]),
+    ),
+    report.identity
+      ? renderSection(
+          "Identity",
+          renderFields([
+            ["Requested", report.identity],
+            ["Resolved ID", report.identityId],
+            [
+              "Resolution",
+              report.identityResolutionOk ? "ok" : report.identityResolutionError,
+            ],
+            [
+              "Identity credential",
+              report.identityCredentialAvailable
+                ? `available (${report.identityCredentialSource})`
+                : "missing",
+            ],
+            ["Publish ready", report.publishReady],
+            [
+              "Diagnostics",
+              report.identityDiagnosticsAvailable
+                ? report.identitySummary
+                : report.identityDiagnosticsError,
+            ],
+            ["Active identity keys", report.identityActiveKeyCount],
+            [
+              "Last posted",
+              report.identityLastPostedAt
+                ? formatTimestamp(report.identityLastPostedAt)
+                : undefined,
+            ],
+            [
+              "Paused until",
+              report.identityPostingPausedUntil
+                ? formatTimestamp(report.identityPostingPausedUntil)
+                : undefined,
+            ],
+            [
+              "Latest blocked write",
+              report.identityLatestBlockedWriteAt
+                ? formatTimestamp(report.identityLatestBlockedWriteAt)
+                : undefined,
+            ],
+            [
+              "Latest blocked reason",
+              report.identityLatestBlockedWriteReasonLabel ||
+                report.identityLatestBlockedWriteReason ||
+                undefined,
+            ],
+          ]),
+        )
+      : undefined,
+    renderSection("Checks", renderChecks(report.checks)),
+    report.suggestions.length > 0
+      ? renderSection("Suggestions", renderBullets(report.suggestions))
+      : undefined,
+  ]);
+}
+
+function renderTokenStatus(
+  configured: boolean,
+  ok: boolean,
+  source: string,
+  error: string,
+): string {
+  if (ok) {
+    return `ok (${source})`;
+  }
+
+  if (configured) {
+    return `failed (${source}): ${error}`;
+  }
+
+  return error || "missing";
+}
+
+function renderChecks(checks: DoctorCheck[]): string {
+  const rows = checks.map((check) => {
+    const status = check.ok ? "ok" : check.required ? "fail" : "warn";
+    const source = check.source ? ` [${check.source}]` : "";
+
+    return `${status.padEnd(4)} ${check.name}${source}\n  ${check.detail}`;
+  });
+
+  return rows.join("\n");
+}

package/src/commands/doctor/suggestions.ts

@@ -0,0 +1,42 @@
+export function buildSuggestions(input: {
+  configFileExists: boolean;
+  openApiOk: boolean;
+  ownerReadReady: boolean;
+  requestedIdentity?: string;
+  identityResolutionOk: boolean;
+  publishReady: boolean;
+  identityDiagnosticsOk: boolean;
+}): string[] {
+  const suggestions: string[] = [];
+
+  if (!input.configFileExists) {
+    suggestions.push("Run `clank config init` to create local config.");
+  }
+
+  if (!input.openApiOk) {
+    suggestions.push("Check `CLANKID_BASE_URL` or `--base-url`, then retry `clank doctor --json`.");
+  }
+
+  if (!input.ownerReadReady) {
+    suggestions.push("Configure a read-only or master token for owner reads with `clank auth login ...`.");
+  }
+
+  if (input.requestedIdentity && !input.identityResolutionOk) {
+    suggestions.push("Use an identity UUID or configure an owner-read token so identity names can be resolved.");
+  }
+
+  if (input.requestedIdentity && !input.publishReady) {
+    suggestions.push("Provide `--identity-key`, `CLANKID_IDENTITY_KEY`, `CLANKID_IDENTITY_KEYS_JSON`, `CLANKID_IDENTITY_KEYS_FILE`, or a master token for publish.");
+  }
+
+  if (
+    input.requestedIdentity &&
+    input.identityResolutionOk &&
+    input.ownerReadReady &&
+    !input.identityDiagnosticsOk
+  ) {
+    suggestions.push("Retry the identity diagnostics with an owner-read token that can read the requested identity.");
+  }
+
+  return suggestions;
+}

package/src/commands/doctor/types.ts

@@ -0,0 +1,75 @@
+import type { createCommandContext } from "../../lib/context";
+
+export interface DoctorCheck {
+  name: string;
+  ok: boolean;
+  required: boolean;
+  source?: string;
+  detail: string;
+}
+
+export interface DoctorReport {
+  cliVersion: string;
+  ok: boolean;
+  status: "ok" | "needs_attention";
+  summary: string;
+  profile: string;
+  configPath: string;
+  configFileExists: boolean;
+  baseUrl: string;
+  hasMasterToken: boolean;
+  masterTokenSource: string;
+  masterTokenOk: boolean;
+  masterTokenError: string;
+  hasReadOnlyToken: boolean;
+  readOnlyTokenSource: string;
+  readOnlyTokenOk: boolean;
+  readOnlyTokenError: string;
+  ownerReadTokenAvailable: boolean;
+  ownerReadTokenSource: string;
+  ownerReadTokenOk: boolean;
+  ownerReadTokenError: string;
+  ownerReadReady: boolean;
+  openApiOk: boolean;
+  openApiError: string;
+  storedIdentityKeys: number;
+  identity: string;
+  identityId: string;
+  identityResolutionOk: boolean;
+  identityResolutionError: string;
+  identityCredentialAvailable: boolean;
+  identityCredentialSource: string;
+  publishReady: boolean;
+  identityDiagnosticsAvailable: boolean;
+  identityDiagnosticsError: string;
+  identitySummary: string;
+  identityStateCodes: string[];
+  identityStateLabels: string[];
+  identityActiveKeyCount: number;
+  identityLastPostedAt: string;
+  identityPostingPausedUntil: string;
+  identityLatestBlockedWriteAt: string;
+  identityLatestBlockedWriteReason: string;
+  identityLatestBlockedWriteReasonLabel: string;
+  checks: DoctorCheck[];
+  suggestions: string[];
+}
+
+export type DoctorContext = Awaited<ReturnType<typeof createCommandContext>>;
+
+export type IdentityDiagnostics = Awaited<
+  ReturnType<DoctorContext["client"]["getIdentityDiagnostics"]>
+>;
+
+export interface CheckResult {
+  ok: boolean;
+  error?: string;
+}
+
+export interface IdentityResolution extends CheckResult {
+  identityId?: string;
+}
+
+export interface IdentityDiagnosticsResult extends CheckResult {
+  value?: IdentityDiagnostics;
+}

package/src/commands/doctor.ts

@@ -0,0 +1,221 @@
+import { createCommandContext } from "../lib/context";
+import { identityFlag, type ParsedArgs } from "../lib/args";
+import { printValue, type Io } from "../lib/output";
+import { CLI_VERSION } from "../lib/version";
+import {
+  resolveMasterToken,
+  resolveOwnerReadToken,
+  resolveIdentityCredential,
+  resolveReadOnlyToken,
+} from "../lib/tokens";
+import {
+  checkConfigPath,
+  formatIdentityDiagnosticsDetail,
+  formatIdentitySummary,
+  maybeFetchIdentityDiagnostics,
+  resolveRequestedIdentity,
+  runCheck,
+  runOptionalCheck,
+} from "./doctor/checks";
+import { renderDoctorReport } from "./doctor/render";
+import { buildSuggestions } from "./doctor/suggestions";
+import type { DoctorCheck, DoctorReport } from "./doctor/types";
+
+export async function runDoctorCommand(
+  args: ParsedArgs,
+  io: Io,
+): Promise<void> {
+  const context = await createCommandContext(args, io);
+  const requestedIdentity = identityFlag(args.flags);
+  const resolvedMasterToken = resolveMasterToken(context.profile);
+  const resolvedReadOnlyToken = resolveReadOnlyToken(context.profile);
+  const resolvedOwnerReadToken = resolveOwnerReadToken(context.profile);
+  const configFileExists = await checkConfigPath(context.configPath);
+
+  const identityResolution = requestedIdentity
+    ? await resolveRequestedIdentity(context, requestedIdentity)
+    : { ok: true, identityId: undefined as string | undefined, error: undefined as string | undefined };
+  const resolvedIdentityCredential = identityResolution.identityId
+    ? resolveIdentityCredential(context.profile, identityResolution.identityId)
+    : 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 identityDiagnostics = await maybeFetchIdentityDiagnostics({
+    context,
+    requestedIdentity,
+    identityResolution,
+    ownerReadReady: ownerReadTokenCheck.ok,
+  });
+
+  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 `clank 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 (requestedIdentity) {
+    checks.push({
+      name: "identity_resolution",
+      ok: identityResolution.ok,
+      required: false,
+      source: requestedIdentity,
+      detail:
+        identityResolution.error ??
+        `Resolved requested identity to ${identityResolution.identityId}.`,
+    });
+    checks.push({
+      name: "publish_token",
+      ok: Boolean(resolvedIdentityCredential?.token),
+      required: false,
+      source: resolvedIdentityCredential?.source ?? "none",
+      detail: resolvedIdentityCredential?.token
+        ? "A publish-capable token is available for the requested identity."
+        : "No publish-capable token is available for the requested identity.",
+    });
+    checks.push({
+      name: "identity_diagnostics",
+      ok: identityDiagnostics.ok,
+      required: false,
+      source: identityResolution.identityId ?? requestedIdentity,
+      detail:
+        identityDiagnostics.error ??
+        formatIdentityDiagnosticsDetail(identityDiagnostics.value),
+    });
+  }
+
+  const publishReady = requestedIdentity
+    ? identityResolution.ok && Boolean(resolvedIdentityCredential?.token)
+    : false;
+  const ownerReadReady = ownerReadTokenCheck.ok;
+  const ok = openApiCheck.ok && ownerReadReady && (!requestedIdentity || publishReady);
+  const suggestions = buildSuggestions({
+    configFileExists,
+    openApiOk: openApiCheck.ok,
+    ownerReadReady,
+    requestedIdentity,
+    identityResolutionOk: identityResolution.ok,
+    publishReady,
+    identityDiagnosticsOk: identityDiagnostics.ok,
+  });
+
+  const report: DoctorReport = {
+    cliVersion: CLI_VERSION,
+    ok,
+    status: ok ? "ok" : "needs_attention",
+    summary: ok
+      ? requestedIdentity
+        ? "CLI can reach the API and publish to the requested identity."
+        : "CLI can reach the API."
+      : requestedIdentity
+        ? "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 ?? "",
+    storedIdentityKeys: Object.keys(context.profile.identityKeys).length,
+    identity: requestedIdentity ?? "",
+    identityId: identityResolution.identityId ?? "",
+    identityResolutionOk: identityResolution.ok,
+    identityResolutionError: identityResolution.error ?? "",
+    identityCredentialAvailable: Boolean(resolvedIdentityCredential?.token),
+    identityCredentialSource: resolvedIdentityCredential?.source ?? "none",
+    publishReady,
+    identityDiagnosticsAvailable: identityDiagnostics.ok,
+    identityDiagnosticsError: identityDiagnostics.error ?? "",
+    identitySummary: formatIdentitySummary(identityDiagnostics.value),
+    identityStateCodes: identityDiagnostics.value?.state_codes ?? [],
+    identityStateLabels: identityDiagnostics.value?.state_labels ?? [],
+    identityActiveKeyCount:
+      identityDiagnostics.value?.active_identity_key_count ?? 0,
+    identityLastPostedAt: identityDiagnostics.value?.last_posted_at ?? "",
+    identityPostingPausedUntil: identityDiagnostics.value?.posting_paused_until ?? "",
+    identityLatestBlockedWriteAt:
+      identityDiagnostics.value?.latest_blocked_write_at ?? "",
+    identityLatestBlockedWriteReason:
+      identityDiagnostics.value?.latest_blocked_write_reason ?? "",
+    identityLatestBlockedWriteReasonLabel:
+      identityDiagnostics.value?.latest_blocked_write_reason_label ?? "",
+    checks,
+    suggestions,
+  };
+
+  printValue(
+    io,
+    context.outputMode,
+    context.outputMode === "json" ? report : renderDoctorReport(report),
+  );
+}