@dharta/cli 0.6.77

package/src/commands/directories.ts

@@ -0,0 +1,136 @@
+import { inferAgentSlug, type AgentInferOptions } from "../agent.js";
+import type { CliContext } from "../context.js";
+import { fmtTs, table } from "../output.js";
+import { parsePositiveInteger } from "../validators.js";
+
+interface ListEnvelope<T> {
+  data: T[];
+}
+
+export interface DirectoryInstance {
+  id: string;
+  scoped_id: string;
+  agent_slug: string | null;
+  seats_count: number;
+  sessions_count: number;
+  last_at: string | null;
+  tokens: number;
+  cpu_seconds: number | null;
+  disk_bytes: number | null;
+  spend_micros: number;
+  cap_cents: number | null;
+}
+
+export interface DirectoryEndUser {
+  id: string;
+  agents_count: number;
+  kartas_count: number;
+  sessions_count: number;
+  first_seen: string | null;
+  last_seen: string | null;
+  tokens: number;
+  spend_micros: number;
+  cap_cents: number | null;
+}
+
+export interface DirectorySession {
+  id: string;
+  agent_slug: string | null;
+  karta_id: string | null;
+  users_count: number;
+  models_count: number;
+  model: string | null;
+  started_at: string | null;
+  last_at: string | null;
+  turns: number;
+  input_tokens: number;
+  output_tokens: number;
+  tokens: number;
+  cost_micros: number;
+}
+
+export interface DirectoryOptions extends AgentInferOptions {
+  limit?: string;
+}
+
+export async function directoryInstancesData(ctx: CliContext, opts: DirectoryOptions): Promise<{ slug: string; data: DirectoryInstance[] }> {
+  validateDirectoryOptions(opts);
+  const slug = await inferAgentSlug(opts);
+  const res = await ctx.http.request<ListEnvelope<DirectoryInstance>>({
+    path: directoryPath(slug, "instances", opts),
+  });
+  return { slug, data: res.data };
+}
+
+export async function directoryInstances(ctx: CliContext, opts: DirectoryOptions): Promise<string> {
+  const { slug, data } = await directoryInstancesData(ctx, opts);
+  if (data.length === 0) return `No kartas for ${slug}. Generate activity with: dharta send "hello" --agent ${slug}`;
+  return table(data.map((row) => ({
+    id: row.id,
+    sessions: String(row.sessions_count),
+    users: String(row.seats_count),
+    tokens: String(row.tokens),
+    last: fmtTs(row.last_at),
+    cap: formatCents(row.cap_cents),
+  })));
+}
+
+export async function directoryEndUsersData(ctx: CliContext, opts: DirectoryOptions): Promise<{ slug: string; data: DirectoryEndUser[] }> {
+  validateDirectoryOptions(opts);
+  const slug = await inferAgentSlug(opts);
+  const res = await ctx.http.request<ListEnvelope<DirectoryEndUser>>({
+    path: directoryPath(slug, "end_users", opts),
+  });
+  return { slug, data: res.data };
+}
+
+export async function directoryEndUsers(ctx: CliContext, opts: DirectoryOptions): Promise<string> {
+  const { slug, data } = await directoryEndUsersData(ctx, opts);
+  if (data.length === 0) return `No users for ${slug}. Generate activity with: dharta send "hello" --agent ${slug}`;
+  return table(data.map((row) => ({
+    id: row.id,
+    kartas: String(row.kartas_count),
+    sessions: String(row.sessions_count),
+    tokens: String(row.tokens),
+    last: fmtTs(row.last_seen),
+    cap: formatCents(row.cap_cents),
+  })));
+}
+
+export async function directorySessionsData(ctx: CliContext, opts: DirectoryOptions): Promise<{ slug: string; data: DirectorySession[] }> {
+  validateDirectoryOptions(opts);
+  const slug = await inferAgentSlug(opts);
+  const res = await ctx.http.request<ListEnvelope<DirectorySession>>({
+    path: directoryPath(slug, "sessions", opts),
+  });
+  return { slug, data: res.data };
+}
+
+export async function directorySessions(ctx: CliContext, opts: DirectoryOptions): Promise<string> {
+  const { slug, data } = await directorySessionsData(ctx, opts);
+  if (data.length === 0) return `No sessions for ${slug}. Generate activity with: dharta send "hello" --agent ${slug}`;
+  return table(data.map((row) => ({
+    id: row.id,
+    karta: row.karta_id ?? "—",
+    users: String(row.users_count),
+    turns: String(row.turns),
+    tokens: String(row.tokens),
+    last: fmtTs(row.last_at),
+  })));
+}
+
+function formatCents(cents: number | null): string {
+  if (cents === null) return "—";
+  return `$${(cents / 100).toFixed(2)}`;
+}
+
+export function validateDirectoryOptions(opts: Pick<DirectoryOptions, "limit"> = {}): void {
+  if (opts.limit !== undefined) parsePositiveInteger(opts.limit, "--limit");
+}
+
+function directoryPath(slug: string, resource: "instances" | "end_users" | "sessions", opts: DirectoryOptions): string {
+  const params = new URLSearchParams();
+  if (opts.limit !== undefined) params.set("limit", String(parsePositiveInteger(opts.limit, "--limit")));
+  const query = params.toString();
+  return `/api/agents/${encodeURIComponent(slug)}/directories/${resource}${query ? `?${query}` : ""}`;
+}

package/src/commands/doctor.ts

@@ -0,0 +1,138 @@
+// `dharta doctor` (RFC 0013 CLI-3 slice): diagnose the things that break
+// the golden path before they break it — PATH shadowing from the retired
+// Python CLI, the uv bootstrap, the DHARTA_RUNTIME escape hatch, and
+// login state. The Phase-2 [env] contract checks (CLI-8) extend this.
+
+import { promises as fs } from "node:fs";
+import { loadConfig } from "../config.js";
+import { resolveRuntime, whichAll, type RuntimeResolveOptions } from "../runtime.js";
+import { installChannel, packageRoot } from "./update.js";
+import { checkNpmLatestVersion, NPM_LATEST_URL } from "../version-check.js";
+
+export interface DoctorReport {
+  lines: string[];
+  ok: boolean;
+}
+
+export interface DoctorOptions extends RuntimeResolveOptions {
+  installRoot?: string;
+  checkLatest?: boolean;
+  currentVersion?: string;
+  fetchImpl?: typeof fetch;
+  latestUrl?: string;
+}
+
+export async function doctor(opts: DoctorOptions = {}): Promise<DoctorReport> {
+  const env = opts.env ?? process.env;
+  const lines: string[] = [];
+  let ok = true;
+
+  // PATH shadowing: a stale pip-installed `dharta` ahead of this CLI
+  // makes every command behave like the retired Python CLI.
+  const kartas = await whichAll("dharta", env);
+  if (kartas.length > 1) {
+    ok = false;
+    lines.push("✗ Multiple `dharta` executables on PATH - the first one wins:");
+    for (const hit of kartas) lines.push(`    ${hit}`);
+    lines.push("  Fix: remove the stale install (often `pip uninstall dharta-runtime` or delete the older path).");
+  } else if (kartas.length === 1) {
+    lines.push(`✓ PATH has a single \`dharta\` (${kartas[0]})`);
+  } else {
+    lines.push("- No `dharta` on PATH (running via npx or a dev build?).");
+  }
+
+  // DHARTA_RUNTIME escape hatch, if set, must point at something real.
+  let runtimeOverrideBroken = false;
+  if (env.DHARTA_RUNTIME) {
+    const stat = await fs.stat(env.DHARTA_RUNTIME).catch(() => null);
+    if (stat) {
+      lines.push(`✓ DHARTA_RUNTIME override -> ${env.DHARTA_RUNTIME} (${stat.isDirectory() ? "checkout" : "executable"})`);
+    } else {
+      ok = false;
+      runtimeOverrideBroken = true;
+      lines.push(`✗ DHARTA_RUNTIME points at ${env.DHARTA_RUNTIME}, which does not exist.`);
+      lines.push("  Fix: unset DHARTA_RUNTIME, or point it at a dharta-runtime checkout or executable.");
+    }
+  }
+
+  // Runtime bootstrap: can `dharta dev` launch the runtime at all?
+  // (Skipped when the override is the already-reported problem.)
+  if (!runtimeOverrideBroken) {
+    try {
+      const runtime = await resolveRuntime(opts);
+      lines.push(`✓ Agent runtime resolves: ${runtime.description}`);
+    } catch (err) {
+      ok = false;
+      const msg = err instanceof Error ? err.message : String(err);
+      lines.push("✗ Agent runtime cannot start:");
+      for (const l of msg.split("\n")) lines.push(`  ${l}`);
+    }
+  }
+
+  if (opts.checkLatest !== false) {
+    const version = await checkLatestVersion(opts);
+    if (version.status === "outdated") {
+      ok = false;
+      lines.push(`✗ CLI is outdated: ${version.current} installed, ${version.latest} available.`);
+      lines.push(`  Fix: ${version.fix}`);
+    } else if (version.status === "current") {
+      lines.push(`✓ CLI version is current: ${version.current}`);
+    } else if (version.status === "ahead") {
+      lines.push(`- CLI version ${version.current} is newer than the latest published npm version (${version.latest}).`);
+    } else {
+      lines.push(`- Could not check latest CLI version: ${version.reason}.`);
+    }
+  }
+
+  // Login state (informational; commands fail with the fix anyway).
+  if (env.DHARTA_API_KEY) {
+    lines.push("✓ Authenticated via DHARTA_API_KEY (environment)");
+  } else {
+    try {
+      const cfg = await loadConfig();
+      if (cfg?.profiles[cfg.default_profile]) {
+        lines.push(`✓ Logged in (profile '${cfg.default_profile}')`);
+      } else {
+        lines.push("- Not logged in. Run `dharta login` before API-backed commands; local checks and browser handoffs still work.");
+      }
+    } catch (err) {
+      // doctor must diagnose a corrupt config, not die on it.
+      ok = false;
+      lines.push(`✗ ~/.dharta/config.toml is unreadable (${err instanceof Error ? err.message : err}).`);
+      lines.push("  Fix: repair or delete it, then `dharta login` again.");
+    }
+  }
+
+  return { lines, ok };
+}
+
+type VersionCheck =
+  | { status: "current"; current: string }
+  | { status: "ahead"; current: string; latest: string }
+  | { status: "outdated"; current: string; latest: string; fix: string }
+  | { status: "unknown"; reason: string };
+
+async function checkLatestVersion(opts: DoctorOptions): Promise<VersionCheck> {
+  const root = opts.installRoot ?? packageRoot();
+  const result = await checkNpmLatestVersion({
+    root,
+    currentVersion: opts.currentVersion,
+    fetchImpl: opts.fetchImpl,
+    latestUrl: opts.latestUrl ?? NPM_LATEST_URL,
+  });
+
+  if (result.status === "unknown") return { status: "unknown", reason: result.reason };
+  if (result.status === "current") return { status: "current", current: result.current };
+  if (result.status === "ahead") return { status: "ahead", current: result.current, latest: result.latest };
+
+  const channel = await installChannel(root).catch(() => "npm" as const);
+  return {
+    status: "outdated",
+    current: result.current,
+    latest: result.latest,
+    fix:
+      channel === "standalone"
+        ? "run `dharta update`"
+        : "run `npm install -g @dharta/cli@latest`",
+  };
+}

package/src/commands/embed-keys.ts

@@ -0,0 +1,237 @@
+import { randomUUID } from "node:crypto";
+import { inferAgentSlug, type AgentInferOptions } from "../agent.js";
+import type { CliContext } from "../context.js";
+import { fmtTs, table } from "../output.js";
+import { normalizeHttpUrl, normalizeNonBlank } from "../validators.js";
+
+export interface EmbedKey {
+  id: string;
+  name: string;
+  prefix: string;
+  allowed_origins: string[];
+  disabled_at: string | null;
+  revoked_at: string | null;
+  created_at: string;
+  last_used_at: string | null;
+  anonymous_max_cost_micros_per_period?: number | null;
+  anonymous_period_unit?: string | null;
+  agent_instance_id?: string | null;
+  identity_verification_enabled?: boolean;
+}
+
+interface IdentityEnvelope {
+  embed_key: EmbedKey;
+  identity_verification_secret?: string;
+}
+
+interface ListEnvelope<T> {
+  data: T[];
+}
+
+interface EmbedKeyEnvelope {
+  embed_key: EmbedKey;
+  secret?: string;
+}
+
+interface EmbedKeyOptions extends AgentInferOptions {
+  origins?: string[];
+}
+
+export async function embedKeysListData(ctx: CliContext, opts: AgentInferOptions): Promise<{ slug: string; data: EmbedKey[] }> {
+  const slug = await inferAgentSlug(opts);
+  const res = await ctx.http.request<ListEnvelope<EmbedKey>>({
+    path: `/api/agents/${encodeURIComponent(slug)}/embed_keys`,
+  });
+  return { slug, data: res.data };
+}
+
+export async function embedKeysList(ctx: CliContext, opts: AgentInferOptions): Promise<string> {
+  const { slug, data } = await embedKeysListData(ctx, opts);
+  if (data.length === 0) return `No embed keys for ${slug}. Create one with: dharta embed-keys create <name> --agent ${slug}`;
+  return table(data.map((key) => row(key)));
+}
+
+export async function embedKeysCreateData(
+  ctx: CliContext,
+  name: string,
+  opts: EmbedKeyOptions,
+): Promise<{ slug: string } & EmbedKeyEnvelope> {
+  validateEmbedKeysCreateInput(name, opts);
+  const normalizedName = normalizeEmbedKeyName(name);
+  const normalizedOrigins = parseOrigins(opts.origins);
+  const slug = await inferAgentSlug(opts);
+  const res = await ctx.http.request<EmbedKeyEnvelope>({
+    method: "POST",
+    path: `/api/agents/${encodeURIComponent(slug)}/embed_keys`,
+    headers: idempotencyHeader(),
+    body: {
+      name: normalizedName,
+      allowed_origins: normalizedOrigins,
+    },
+  });
+  return { slug, ...res };
+}
+
+export async function embedKeysCreate(ctx: CliContext, name: string, opts: EmbedKeyOptions): Promise<string> {
+  const res = await embedKeysCreateData(ctx, name, opts);
+  return [
+    `Created embed key ${res.embed_key.prefix} (${res.embed_key.id}) for ${res.slug}.`,
+    "Secret (shown once - update your widget now):",
+    res.secret ?? "",
+  ].join("\n");
+}
+
+export function validateEmbedKeysCreateInput(name: string, opts: EmbedKeyOptions): void {
+  normalizeEmbedKeyName(name);
+  if (opts.origins !== undefined) parseOrigins(opts.origins);
+}
+
+export async function embedKeysRotateData(ctx: CliContext, id: string, opts: AgentInferOptions): Promise<{ slug: string } & EmbedKeyEnvelope> {
+  const normalizedId = normalizeNonBlank(id, "Embed key id");
+  const slug = await inferAgentSlug(opts);
+  const res = await ctx.http.request<EmbedKeyEnvelope>({
+    method: "POST",
+    path: `/api/agents/${encodeURIComponent(slug)}/embed_keys/${encodeURIComponent(normalizedId)}/rotate`,
+    headers: idempotencyHeader(),
+  });
+  return { slug, ...res };
+}
+
+export async function embedKeysRotate(ctx: CliContext, id: string, opts: AgentInferOptions): Promise<string> {
+  const res = await embedKeysRotateData(ctx, id, opts);
+  return [
+    `Rotated embed key ${res.embed_key.prefix} (${res.embed_key.id}) for ${res.slug}.`,
+    "Secret (shown once - update your widget now):",
+    res.secret ?? "",
+  ].join("\n");
+}
+
+export async function embedKeysToggleData(
+  ctx: CliContext,
+  id: string,
+  action: "enable" | "disable",
+  opts: AgentInferOptions,
+): Promise<{ slug: string } & EmbedKeyEnvelope> {
+  const normalizedId = normalizeNonBlank(id, "Embed key id");
+  const slug = await inferAgentSlug(opts);
+  const res = await ctx.http.request<EmbedKeyEnvelope>({
+    method: "POST",
+    path: `/api/agents/${encodeURIComponent(slug)}/embed_keys/${encodeURIComponent(normalizedId)}/${action}`,
+    headers: idempotencyHeader(),
+  });
+  return { slug, ...res };
+}
+
+export async function embedKeysToggle(
+  ctx: CliContext,
+  id: string,
+  action: "enable" | "disable",
+  opts: AgentInferOptions,
+): Promise<string> {
+  const res = await embedKeysToggleData(ctx, id, action, opts);
+  return `${action === "enable" ? "Enabled" : "Disabled"} embed key ${res.embed_key.prefix} (${res.embed_key.id}).`;
+}
+
+export async function embedKeysSetIdentityData(
+  ctx: CliContext,
+  id: string,
+  opts: AgentInferOptions,
+): Promise<{ slug: string } & IdentityEnvelope> {
+  const normalizedId = normalizeNonBlank(id, "Embed key id");
+  const slug = await inferAgentSlug(opts);
+  const res = await ctx.http.request<IdentityEnvelope>({
+    method: "POST",
+    path: `/api/agents/${encodeURIComponent(slug)}/embed_keys/${encodeURIComponent(normalizedId)}/identity`,
+    headers: idempotencyHeader(),
+  });
+  return { slug, ...res };
+}
+
+export async function embedKeysSetIdentity(ctx: CliContext, id: string, opts: AgentInferOptions): Promise<string> {
+  const res = await embedKeysSetIdentityData(ctx, id, opts);
+  return [
+    `Enabled verified identity for embed key ${res.embed_key.prefix} (${res.embed_key.id}) on ${res.slug}.`,
+    "Identity signing secret (shown once - copy it into your backend now; it will not be shown again):",
+    res.identity_verification_secret ?? "",
+  ].join("\n");
+}
+
+export async function embedKeysClearIdentityData(
+  ctx: CliContext,
+  id: string,
+  opts: AgentInferOptions,
+): Promise<{ slug: string } & EmbedKeyEnvelope> {
+  const normalizedId = normalizeNonBlank(id, "Embed key id");
+  const slug = await inferAgentSlug(opts);
+  const res = await ctx.http.request<EmbedKeyEnvelope>({
+    method: "DELETE",
+    path: `/api/agents/${encodeURIComponent(slug)}/embed_keys/${encodeURIComponent(normalizedId)}/identity`,
+    headers: idempotencyHeader(),
+  });
+  return { slug, ...res };
+}
+
+export async function embedKeysClearIdentity(ctx: CliContext, id: string, opts: AgentInferOptions): Promise<string> {
+  const res = await embedKeysClearIdentityData(ctx, id, opts);
+  return `Disabled verified identity for embed key ${res.embed_key.prefix} (${res.embed_key.id}) on ${res.slug}.`;
+}
+
+export async function embedKeysRevokeData(ctx: CliContext, id: string, opts: AgentInferOptions): Promise<{ slug: string; id: string; revoked: boolean }> {
+  const normalizedId = normalizeNonBlank(id, "Embed key id");
+  const slug = await inferAgentSlug(opts);
+  await ctx.http.request<void>({
+    method: "DELETE",
+    path: `/api/agents/${encodeURIComponent(slug)}/embed_keys/${encodeURIComponent(normalizedId)}`,
+    headers: idempotencyHeader(),
+  });
+  return { slug, id: normalizedId, revoked: true };
+}
+
+export async function embedKeysRevoke(ctx: CliContext, id: string, opts: AgentInferOptions): Promise<string> {
+  const res = await embedKeysRevokeData(ctx, id, opts);
+  return `Revoked embed key ${res.id} for ${res.slug}.`;
+}
+
+export function parseOrigins(input: string[] | undefined): string[] {
+  if (input === undefined) return [];
+  const origins = input
+    .flatMap((value) => value.split(/[,\s]+/))
+    .map((value) => value.trim())
+    .filter(Boolean);
+  if (origins.length === 0) {
+    throw new Error("--origin must include at least one origin, e.g. --origin https://app.example.com.");
+  }
+  return origins.map((origin) => normalizeOrigin(origin));
+}
+
+function normalizeOrigin(origin: string): string {
+  const normalized = normalizeHttpUrl(origin, "--origin");
+  const parsed = new URL(normalized);
+  if (parsed.pathname !== "/" || parsed.search || parsed.hash) {
+    throw new Error("--origin must be an origin like https://app.example.com, without a path, query, or fragment.");
+  }
+  return parsed.origin;
+}
+
+function row(key: EmbedKey): Record<string, string> {
+  return {
+    prefix: key.prefix,
+    name: key.name,
+    origins: key.allowed_origins.join(",") || "-",
+    disabled: fmtTs(key.disabled_at),
+    revoked: fmtTs(key.revoked_at),
+    created: fmtTs(key.created_at),
+  };
+}
+
+function idempotencyHeader(): Record<string, string> {
+  return { "Idempotency-Key": randomUUID() };
+}
+
+function normalizeEmbedKeyName(name: string): string {
+  const normalized = name.trim();
+  if (!normalized) {
+    throw new Error("Embed key name cannot be blank.");
+  }
+  return normalized;
+}