@dharta/cli 0.6.77

package/node_modules/@dharta/sdk/src/resources.ts

@@ -0,0 +1,197 @@
+import type { HttpClient } from "./http.js";
+import type {
+  ApiKey,
+  ApiKeyCreateResponse,
+  ApiKeyScope,
+  BillingStatus,
+  ModelKey,
+  ModelKeyCreateParams,
+  ModelKeyProvider,
+  UsageSummary,
+  WebhookEndpoint,
+  WebhookEndpointCreateResponse,
+  WebhookEventType,
+} from "./types.js";
+
+interface ListEnvelope<T> {
+  data: T[];
+}
+
+interface ModelKeyEnvelope {
+  model_key: ModelKey;
+}
+
+interface WebhookEndpointEnvelope {
+  webhook_endpoint: WebhookEndpoint;
+}
+
+export class ApiKeysResource {
+  constructor(private readonly http: HttpClient) {}
+
+  async list(): Promise<ApiKey[]> {
+    const res = await this.http.request<ListEnvelope<ApiKey>>({ path: "/api_keys" });
+    return res.data;
+  }
+
+  async create(name: string, scopes: ApiKeyScope[]): Promise<ApiKeyCreateResponse> {
+    return this.http.request<ApiKeyCreateResponse>({
+      method: "POST",
+      path: "/api_keys",
+      headers: idempotencyHeaders(),
+      body: { name, scopes },
+    });
+  }
+
+  async rename(id: string, name: string): Promise<ApiKey> {
+    const res = await this.http.request<{ api_key: ApiKey }>({
+      method: "PATCH",
+      path: `/api_keys/${encodeURIComponent(id)}`,
+      headers: idempotencyHeaders(),
+      body: { name },
+    });
+    return res.api_key;
+  }
+
+  async revoke(id: string): Promise<void> {
+    await this.http.request<void>({
+      method: "DELETE",
+      path: `/api_keys/${encodeURIComponent(id)}`,
+      headers: idempotencyHeaders(),
+    });
+  }
+}
+
+export class ModelKeysResource {
+  constructor(private readonly http: HttpClient) {}
+
+  async list(): Promise<ModelKey[]> {
+    const res = await this.http.request<ListEnvelope<ModelKey>>({ path: "/model_keys" });
+    return res.data;
+  }
+
+  async create(provider: ModelKeyProvider, plaintext: string, name?: string): Promise<ModelKey>;
+  async create(params: ModelKeyCreateParams): Promise<ModelKey>;
+  async create(
+    providerOrParams: ModelKeyProvider | ModelKeyCreateParams,
+    plaintext?: string,
+    name?: string,
+  ): Promise<ModelKey> {
+    const body = typeof providerOrParams === "string"
+      ? { provider: providerOrParams, plaintext, name }
+      : providerOrParams;
+    const res = await this.http.request<ModelKeyEnvelope>({
+      method: "POST",
+      path: "/model_keys",
+      headers: idempotencyHeaders(),
+      body,
+    });
+    return res.model_key;
+  }
+
+  async revoke(id: string | number): Promise<void> {
+    await this.http.request<void>({
+      method: "DELETE",
+      path: `/model_keys/${encodeURIComponent(String(id))}`,
+      headers: idempotencyHeaders(),
+    });
+  }
+}
+
+export interface WebhookEndpointCreateParams {
+  url: string;
+  name?: string;
+  event_types?: WebhookEventType[];
+}
+
+export interface WebhookEndpointUpdateParams {
+  name?: string;
+  url?: string;
+  event_types?: WebhookEventType[];
+}
+
+export class WebhookEndpointsResource {
+  constructor(private readonly http: HttpClient) {}
+
+  async list(): Promise<WebhookEndpoint[]> {
+    const res = await this.http.request<ListEnvelope<WebhookEndpoint>>({ path: "/api/webhook_endpoints" });
+    return res.data;
+  }
+
+  async create(params: WebhookEndpointCreateParams): Promise<WebhookEndpointCreateResponse> {
+    return this.http.request<WebhookEndpointCreateResponse>({
+      method: "POST",
+      path: "/api/webhook_endpoints",
+      headers: idempotencyHeaders(),
+      body: params,
+    });
+  }
+
+  async update(id: string, params: WebhookEndpointUpdateParams): Promise<WebhookEndpoint> {
+    const res = await this.http.request<WebhookEndpointEnvelope>({
+      method: "PATCH",
+      path: `/api/webhook_endpoints/${encodeURIComponent(id)}`,
+      headers: idempotencyHeaders(),
+      body: params,
+    });
+    return res.webhook_endpoint;
+  }
+
+  async enable(id: string): Promise<WebhookEndpoint> {
+    const res = await this.http.request<WebhookEndpointEnvelope>({
+      method: "POST",
+      path: `/api/webhook_endpoints/${encodeURIComponent(id)}/enable`,
+      headers: idempotencyHeaders(),
+    });
+    return res.webhook_endpoint;
+  }
+
+  async delete(id: string): Promise<void> {
+    await this.http.request<void>({
+      method: "DELETE",
+      path: `/api/webhook_endpoints/${encodeURIComponent(id)}`,
+      headers: idempotencyHeaders(),
+    });
+  }
+}
+
+export class UsageResource {
+  constructor(private readonly http: HttpClient) {}
+
+  async summary(): Promise<UsageSummary> {
+    return this.http.request<UsageSummary>({ path: "/api/usage" });
+  }
+}
+
+export class BillingResource {
+  constructor(private readonly http: HttpClient) {}
+
+  async status(): Promise<BillingStatus> {
+    return this.http.request<BillingStatus>({ path: "/api/billing" });
+  }
+}
+
+function idempotencyHeaders(): Record<string, string> {
+  return { "Idempotency-Key": randomIdempotencyKey() };
+}
+
+function randomIdempotencyKey(): string {
+  if (globalThis.crypto?.randomUUID) return globalThis.crypto.randomUUID();
+  const bytes = new Uint8Array(16);
+  if (globalThis.crypto?.getRandomValues) {
+    globalThis.crypto.getRandomValues(bytes);
+  } else {
+    for (let i = 0; i < bytes.length; i += 1) {
+      bytes[i] = Math.floor(Math.random() * 256);
+    }
+  }
+  bytes[6] = (bytes[6] & 0x0f) | 0x40;
+  bytes[8] = (bytes[8] & 0x3f) | 0x80;
+  const hex = [...bytes].map((byte) => byte.toString(16).padStart(2, "0"));
+  return [
+    hex.slice(0, 4).join(""),
+    hex.slice(4, 6).join(""),
+    hex.slice(6, 8).join(""),
+    hex.slice(8, 10).join(""),
+    hex.slice(10, 16).join(""),
+  ].join("-");
+}

package/node_modules/@dharta/sdk/src/types.ts

@@ -0,0 +1,179 @@
+// Hand-written types mirroring the Rails OpenAPI spec
+// (apps/dharta-web/app/lib/openapi/spec.rb). Keep tight: only what
+// the Dharta API actually returns / accepts. If a server field
+// disappears, this file should drop it on the next bump rather than
+// carrying dead optionals forever.
+
+export const API_KEY_SCOPES = [
+  "agents:read",
+  "appearance:read",
+  "analytics:read",
+  "caps:read",
+  "directories:read",
+  "embed_keys:read",
+  "env:read",
+  "keys:read",
+  "members:read",
+  "model_keys:read",
+  "releases:read",
+  "schedules:read",
+  "sessions:read",
+  "source_repos:read",
+  "webhooks:read",
+  "agents:write",
+  "appearance:write",
+  "env:write",
+  "releases:write",
+  "schedules:write",
+  "webhooks:write",
+  "embed_keys:write",
+  "caps:write",
+  "source_repos:write",
+  "env:secrets:read",
+  "source_archives:read",
+  "workspace_tokens:create",
+  "audit_log:export",
+  "members:invite",
+  "members:write",
+  "members:owner_role:write",
+  "agents:delete",
+  "keys:write",
+  "model_keys:write",
+  "billing:read",
+] as const;
+
+export type ApiKeyScope = (typeof API_KEY_SCOPES)[number];
+
+export type ModelKeyProvider =
+  | "anthropic"
+  | "openai"
+  | "bedrock"
+  | "vertex"
+  | "openrouter"
+  | "xai"
+  | "google";
+
+export type ModelApiFormat =
+  | "anthropic_messages"
+  | "openai_chat_completions"
+  | "openai_responses"
+  | "bedrock_converse"
+  | "vertex_generate_content";
+
+export type ModelReasoningEffort = "low" | "medium" | "high";
+
+export interface ModelParameters {
+  temperature?: number;
+  top_p?: number;
+  max_output_tokens?: number;
+  reasoning_effort?: ModelReasoningEffort;
+  provider_options?: {
+    openai?: {
+      service_tier?: "auto" | "default" | "flex" | "priority";
+      verbosity?: "low" | "medium" | "high";
+    };
+  };
+}
+
+export const WEBHOOK_EVENT_TYPES = [
+  "api_key.created",
+  "api_key.revoked",
+  "subscription.created",
+  "subscription.updated",
+  "subscription.canceled",
+  "invoice.paid",
+  "invoice.payment_failed",
+  "organization.suspended",
+  "organization.resumed",
+  "usage.budget_threshold_reached",
+  "usage.budget_exhausted",
+  "session.started",
+  "turn.completed",
+  "turn.failed",
+] as const;
+
+export type WebhookEventType = (typeof WEBHOOK_EVENT_TYPES)[number];
+
+export interface ApiKey {
+  id: string;
+  name: string;
+  prefix: string;
+  scopes: ApiKeyScope[];
+  mode?: "live" | "test";
+  expires_at?: string | null;
+  created_at: string;
+  last_used_at: string | null;
+  revoked_at: string | null;
+}
+
+export interface ApiKeyCreateResponse {
+  api_key: ApiKey;
+  // Plaintext secret — shown exactly once, on create. Store it now.
+  secret: string;
+}
+
+export interface ModelKey {
+  id: number;
+  provider: ModelKeyProvider;
+  name: string;
+  tail: string;
+  auth_type: "api_key" | "oauth_subscription";
+  endpoint_url: string | null;
+  api_format: ModelApiFormat | null;
+  created_at: string;
+  last_verified_at: string | null;
+  verification_error: string | null;
+  revoked_at: string | null;
+}
+
+export interface ModelKeyCreateParams {
+  provider: ModelKeyProvider;
+  plaintext: string;
+  name?: string;
+  auth_type?: "api_key" | "oauth_subscription";
+  endpoint_url?: string;
+  api_format?: ModelApiFormat;
+}
+
+export interface WebhookEndpoint {
+  id: string;
+  name: string;
+  url: string;
+  event_types: WebhookEventType[];
+  enabled: boolean;
+  consecutive_failures: number;
+  disabled_at: string | null;
+  created_at: string;
+}
+
+export interface WebhookEndpointCreateResponse {
+  webhook_endpoint: WebhookEndpoint;
+  secret: string;
+}
+
+export interface UsageSummary {
+  totals: {
+    input_tokens?: number;
+    output_tokens?: number;
+    requests?: number;
+    [k: string]: number | undefined;
+  };
+  budget: {
+    monthly_cap_cents: number | null;
+    period_start: string;
+    period_end: string;
+  } | null;
+}
+
+export interface BillingStatus {
+  plan_key: string;
+  stripe_configured: boolean;
+  subscription_state: string | null;
+  current_period_end: string | null;
+}
+
+export interface ErrorBody {
+  error: string;
+  message?: string;
+  details?: Record<string, unknown>;
+}

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@dharta/cli",
+  "version": "0.6.77",
+  "description": "Command-line interface for the Dharta API.",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "dharta": "./dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md",
+    "templates"
+  ],
+  "bundledDependencies": [
+    "@dharta/sdk"
+  ],
+  "scripts": {
+    "build": "node -e \"fs.rmSync('dist', { recursive: true, force: true })\" && tsc -p tsconfig.json",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "engines": {
+    "node": ">=18.17.0"
+  },
+  "dependencies": {
+    "@dharta/sdk": "^0.6.77",
+    "@iarna/toml": "^2.2.5",
+    "commander": "^15.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^26.0.1",
+    "msw": "^2.14.6",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.9"
+  }
+}

package/src/agent.ts

@@ -0,0 +1,147 @@
+// Agent identity inference, shared by every per-agent command (RFC 0024 + the
+// CLI surface spec). The agent a command targets comes from its dharta.toml -
+// NOT the `dharta` git remote, which now points at the SOURCE REPO (one repo,
+// many agents), so remote-slug inference would resolve the wrong thing.
+
+import * as path from "node:path";
+import { existsSync, statSync } from "node:fs";
+import { findGitRoot, scanAgentFolders, describeFolder, type AgentFolder } from "./setup-scan.js";
+import { normalizeNonBlank } from "./validators.js";
+
+const AGENT_SLUG_FORMAT = /^[a-z0-9][a-z0-9-]{0,62}$/;
+const MAX_AGENT_NAME_CHARACTERS = 100;
+
+export interface AgentInferOptions {
+  agent?: string; // -a/--agent (or an explicit [slug]); the deployed agent
+  project?: string; // deprecated alias for `agent` (the -p/--project flag)
+  path?: string; // [path] positional - the agent's folder
+  dir?: string; // cwd (default process.cwd())
+  env?: NodeJS.ProcessEnv;
+  scan?: (root: string, opts: { isGitRepo: boolean }) => Promise<AgentFolder[]>; // test seam
+}
+
+// Resolve the agent slug a per-agent command operates on. Order (explicit
+// beats inferred): --agent/-p, an explicit [path], the nearest containing
+// agent folder, the repo's sole agent, then DHARTA_PROJECT (CI). A multi-agent
+// repo root with no selector is a loud error rather than a wrong guess.
+// Identity for a scanned agent folder: an explicit dharta.toml `slug` wins
+// (pinned identity, free-form display name); otherwise derive from the name.
+function slugForFolder(folder: { slug?: string; name?: string }): string {
+  if (folder.slug) return validateAgentSlug(folder.slug, "dharta.toml slug");
+  return deriveSlug(folder.name as string);
+}
+
+export async function inferAgentSlug(opts: AgentInferOptions = {}): Promise<string> {
+  validateAgentSelectorOptions(opts);
+  if (opts.agent !== undefined) return normalizeAgentSlug(opts.agent, "--agent");
+  if (opts.project !== undefined) return normalizeAgentSlug(opts.project, "--project");
+
+  const cwd = path.resolve(opts.dir ?? process.cwd());
+
+  if (opts.path) {
+    const dir = path.resolve(cwd, opts.path);
+    const folder = await describeFolder(dir, path.basename(dir));
+    if (folder.name) return slugForFolder(folder);
+    throw new Error(`No agent at ${opts.path} - it has no dharta.toml with a name.`);
+  }
+
+  const gitRoot = findGitRoot(cwd);
+  let localDir = cwd;
+  for (;;) {
+    if (existsSync(path.join(localDir, "dharta.toml"))) {
+      const local = await describeFolder(localDir, path.basename(localDir));
+      if (local.name) return slugForFolder(local);
+      throw new Error(`${path.join(localDir, "dharta.toml")} must declare an agent name.`);
+    }
+    if (gitRoot && localDir === path.resolve(gitRoot)) break;
+    const parent = path.dirname(localDir);
+    if (parent === localDir) break;
+    localDir = parent;
+  }
+  const scan = opts.scan ?? scanAgentFolders;
+  const agents = (await scan(gitRoot ?? cwd, { isGitRepo: !!gitRoot })).filter((f) => f.name);
+  const containing = agents
+    .filter((folder) => cwd === path.resolve(folder.dir) || cwd.startsWith(`${path.resolve(folder.dir)}${path.sep}`))
+    .sort((a, b) => path.resolve(b.dir).length - path.resolve(a.dir).length);
+  if (containing.length > 0) return slugForFolder(containing[0]);
+  if (agents.length === 1) return slugForFolder(agents[0]);
+
+  // The sole local agent wins over the env (local context beats CI); the env
+  // is the fallback when the local context is empty or ambiguous (a monorepo
+  // CI job names its target with DHARTA_PROJECT).
+  const envAgent = (opts.env ?? process.env).DHARTA_PROJECT;
+  if (envAgent !== undefined) return normalizeAgentSlug(envAgent, "DHARTA_PROJECT");
+
+  if (agents.length === 0) {
+    throw new Error(
+      "No agent here. Run inside an agent folder (one with a dharta.toml), or pass --agent <slug>.",
+    );
+  }
+  const list = agents.map((f) => f.rel).join(", ");
+  throw new Error(`Multiple agents here (${list}). Pass --agent <slug> or a [path] to pick one.`);
+}
+
+export function validateAgentSelectorOptions(opts: Pick<AgentInferOptions, "agent" | "project" | "dir"> = {}): void {
+  if (opts.agent !== undefined) validateAgentSlug(opts.agent, "--agent");
+  if (opts.project !== undefined) validateAgentSlug(opts.project, "--project");
+  if (opts.dir === undefined) return;
+  const dir = path.resolve(normalizeNonBlank(opts.dir, "--dir"));
+  try {
+    if (!statSync(dir).isDirectory()) {
+      throw new Error(`Cannot use --dir ${dir}: expected a directory.`);
+    }
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") {
+      throw new Error(`Cannot use --dir ${dir}: directory does not exist.`);
+    }
+    throw error;
+  }
+}
+
+// https://git.dharta.ai/{org}/{slug}.git -> slug. Still used by `deploy` to read
+// the wired `dharta` remote (a source-repo slug there, which is what deploy wants).
+export function slugFromRemote(url: string): string | null {
+  const match = url.match(/\/([^/]+)\/([^/]+?)(\.git)?$/);
+  return match ? match[2] : null;
+}
+
+// Port of the server's Agent.derive_slug: lowercase, underscores/spaces
+// -> hyphens, drop disallowed chars, truncate to 63, strip edge hyphens, fall
+// back to "agent". Shared by setup (default name), the agent resolver above,
+// and the live preview JS.
+export function deriveSlug(name: string): string {
+  let base = name.toLowerCase().replace(/[_\s]+/g, "-").replace(/[^a-z0-9-]/g, "");
+  base = base.slice(0, 63).replace(/^-+|-+$/g, "");
+  return base || "agent";
+}
+
+export function validateAgentSlug(value: string, label: string): string {
+  const normalized = normalizeNonBlank(value, label);
+  if (!AGENT_SLUG_FORMAT.test(normalized)) {
+    const suggestion = slugSuggestion(normalized);
+    throw new Error(
+      `${label} must be a valid agent slug: lowercase letters, digits, hyphens; max 63.` +
+        (suggestion ? ` Did you mean ${suggestion}?` : ""),
+    );
+  }
+  return normalized;
+}
+
+// Mirrors Agent's public display-name contract. Count Unicode code points,
+// rather than UTF-16 code units, so client-side validation agrees with Ruby's
+// String#length for non-ASCII names.
+export function validateAgentName(value: string, label = "agent name"): string {
+  const normalized = normalizeNonBlank(value, label);
+  if ([...normalized].length > MAX_AGENT_NAME_CHARACTERS) {
+    throw new Error(`${label} must be 1-${MAX_AGENT_NAME_CHARACTERS} characters.`);
+  }
+  return normalized;
+}
+
+const normalizeAgentSlug = validateAgentSlug;
+
+function slugSuggestion(value: string): string | null {
+  if (!/^[A-Za-z0-9 _-]+$/.test(value)) return null;
+  const suggestion = deriveSlug(value);
+  return suggestion !== value && AGENT_SLUG_FORMAT.test(suggestion) ? suggestion : null;
+}

package/src/api-error.ts

@@ -0,0 +1,88 @@
+// Error formatting for the CLI's control-plane calls. Passed to the SDK
+// HttpClient as `formatError` so CLI errors keep their human message + the
+// `err.status`/`err.body` shape (instead of the SDK's typed errorFor()
+// hierarchy, which the CLI doesn't surface).
+
+import { SENSITIVE_API_KEY_SCOPES } from "./commands/scopes.js";
+
+export function cliFormatError(status: number, parsed: unknown): Error {
+  // Server messages already name fixes (e.g. the transcript-access 403 points
+  // at the settings page) - keep them verbatim. Rails sends `message`; the
+  // agent host (FastAPI) sends `detail`; some raw upload endpoints send
+  // `error`.
+  const body = parsed && typeof parsed === "object" ? (parsed as Record<string, unknown>) : {};
+  const serverMessage =
+    typeof body.message === "string"
+      ? body.message
+      : typeof body.detail === "string"
+        ? body.detail
+        : typeof body.error === "string" && !looksLikeMachineCode(body.error)
+          ? body.error
+          : null;
+  let message = serverMessage ?? `Dharta API error ${status}`;
+  if (status === 401) {
+    message += `${message.endsWith(".") ? "" : "."} Run \`dharta login\` to re-authenticate (or check DHARTA_API_KEY).`;
+  } else if (status === 403 && /scope/i.test(message)) {
+    message += `${message.endsWith(".") ? "" : "."} Run \`dharta auth status\` to inspect the active key, or \`dharta open api-keys\` to manage key scopes.`;
+    const sensitiveScopes = missingSensitiveScopes(message);
+    if (sensitiveScopes.length > 0) {
+      message += ` Sensitive scopes (${sensitiveScopes.join(", ")}) require a bounded key with --expires-at within 90 days.`;
+    }
+  } else if (status === 404 && (!serverMessage || isGenericNotFound(serverMessage))) {
+    message +=
+      `${message.endsWith(".") ? "" : "."} ` +
+      "Check the id or agent slug; for agent commands, run `dharta agent list`. " +
+      "Run `dharta auth status` to confirm the active host; DHARTA_BASE_URL must point at the Dharta control API.";
+  }
+  const err = new Error(message) as Error & { status?: number; body?: unknown };
+  err.status = status;
+  err.body = parsed;
+  return err;
+}
+
+export function cliFormatNetworkError(url: string, error: unknown): Error {
+  const origin = new URL(url).origin;
+  return new Error(
+    `Could not reach Dharta at ${origin} (${formatCause(error)}). ` +
+      "Check your network and DHARTA_BASE_URL, then try again.",
+  );
+}
+
+export async function cliFormatRawError(res: Response): Promise<Error> {
+  const text = await res.text();
+  let parsed: unknown = null;
+  if (text.length > 0) {
+    try {
+      parsed = JSON.parse(text);
+    } catch {
+      parsed = text;
+    }
+  }
+  return cliFormatError(res.status, parsed);
+}
+
+function missingSensitiveScopes(message: string): string[] {
+  const mentioned = new Set(mentionedScopes(message));
+  if (/one of required scopes/i.test(message) && Array.from(mentioned).some((scope) => !SENSITIVE_API_KEY_SCOPES.has(scope))) {
+    return [];
+  }
+  return Array.from(SENSITIVE_API_KEY_SCOPES).filter((scope) => mentioned.has(scope));
+}
+
+function mentionedScopes(message: string): string[] {
+  const required = message.match(/required scopes?:\s*([a-z0-9_:,\s-]+)/i)?.[1];
+  const source = required ?? message;
+  return source.match(/[a-z][a-z0-9_]*(?::[a-z][a-z0-9_]*)?/g) ?? [];
+}
+
+function formatCause(error: unknown): string {
+  return error instanceof Error && error.message ? error.message : String(error);
+}
+
+function looksLikeMachineCode(value: string): boolean {
+  return /^[a-z][a-z0-9_:-]*$/.test(value);
+}
+
+function isGenericNotFound(value: string): boolean {
+  return /^resource not found\.?$/i.test(value.trim()) || /^not found\.?$/i.test(value.trim());
+}

package/src/browser.ts

@@ -0,0 +1,20 @@
+import { spawn } from "node:child_process";
+
+// Best-effort browser launch; callers always print the URL too, so a
+// headless box still works.
+export function openBrowser(url: string): Promise<boolean> {
+  const cmd =
+    process.platform === "darwin"
+      ? "open"
+      : process.platform === "win32"
+        ? "explorer"
+        : "xdg-open";
+  return new Promise((resolve) => {
+    const proc = spawn(cmd, [url], { stdio: "ignore", detached: true });
+    proc.on("error", () => resolve(false));
+    proc.on("spawn", () => {
+      proc.unref();
+      resolve(true);
+    });
+  });
+}