@dharta/cli 0.6.77

package/src/commands/caps.ts

@@ -0,0 +1,302 @@
+import { randomUUID } from "node:crypto";
+import type { CliContext } from "../context.js";
+import { parseDollarAmountToCents } from "../money.js";
+
+export interface Budget {
+  period: string;
+  max_cost_cents: number | null;
+  stop_usage: boolean;
+  alerts_enabled: boolean;
+  alert_threshold_pct: number;
+  additional_recipient_user_ids: number[];
+  max_total_tokens: number | null;
+  max_input_tokens: number | null;
+  max_output_tokens: number | null;
+}
+
+export interface BudgetUsage {
+  period_cost_cents: number;
+  total_tokens: number;
+  percent_used: number | null;
+}
+
+export interface BudgetEnvelope {
+  budget: Budget;
+  usage: BudgetUsage;
+}
+
+export interface BudgetSetOptions {
+  amount?: string;
+  hardStop?: boolean;
+  soft?: boolean;
+  enableAlerts?: boolean;
+  disableAlerts?: boolean;
+  alertThreshold?: string;
+  recipientUserId?: string[];
+}
+
+export interface EntityCap {
+  id: number;
+  cap_cents: number;
+  created_at: string;
+  updated_at: string;
+}
+
+export interface InstanceCapEnvelope {
+  type: "instance";
+  raw_instance_id: string;
+  agent_instance_id: string;
+  spend_micros: number;
+  cap: EntityCap | null;
+  changed?: boolean;
+}
+
+export interface EndUserCapEnvelope {
+  type: "end_user";
+  end_user_id: string;
+  spend_micros: number;
+  cap: EntityCap | null;
+  changed?: boolean;
+}
+
+export interface SeatCapEnvelope {
+  type: "seat";
+  raw_instance_id: string;
+  agent_instance_id: string;
+  end_user_id: string;
+  spend_micros: number;
+  cap: EntityCap | null;
+  changed?: boolean;
+}
+
+export interface CapSetOptions {
+  amount?: string;
+  clear?: boolean;
+}
+
+export async function capsBudgetData(ctx: CliContext): Promise<BudgetEnvelope> {
+  return ctx.http.request<BudgetEnvelope>({ path: "/api/limits/budget" });
+}
+
+export async function capsBudget(ctx: CliContext): Promise<string> {
+  const { budget, usage } = await capsBudgetData(ctx);
+  const hasBudget = budget.max_cost_cents !== null;
+  return [
+    `Monthly budget: ${formatMoney(budget.max_cost_cents)}`,
+    `Usage this period: ${formatMoney(usage.period_cost_cents)}`,
+    `Hard stop: ${hasBudget ? (budget.stop_usage ? "enabled" : "disabled") : "not active (no monthly budget)"}`,
+    `Alerts: ${hasBudget ? (budget.alerts_enabled ? `enabled at ${budget.alert_threshold_pct}%` : "disabled") : "not active (no monthly budget)"}`,
+  ].join("\n");
+}
+
+export async function capsBudgetSetData(ctx: CliContext, opts: BudgetSetOptions): Promise<BudgetEnvelope> {
+  validateBudgetSetOptions(opts);
+  const body: Record<string, unknown> = {
+    max_cost_cents: dollarsToCents(opts.amount),
+  };
+  const stopUsage = stopUsageOption(opts);
+  if (stopUsage !== undefined) body.stop_usage = stopUsage;
+  const alertsEnabled = alertsOption(opts);
+  if (alertsEnabled !== undefined) body.alerts_enabled = alertsEnabled;
+  if (opts.alertThreshold !== undefined) {
+    body.alert_threshold_pct = parseWholeNumberInRange(opts.alertThreshold, "--alert-threshold", 0, 100);
+  }
+  if (opts.recipientUserId?.length) {
+    body.additional_recipient_user_ids = opts.recipientUserId.map((id) => parsePositiveWholeNumber(id, "--recipient-user-id"));
+  }
+
+  return ctx.http.request<BudgetEnvelope>({
+    method: "PATCH",
+    path: "/api/limits/budget",
+    headers: { "Idempotency-Key": randomUUID() },
+    body,
+  });
+}
+
+export async function capsBudgetSet(ctx: CliContext, opts: BudgetSetOptions): Promise<string> {
+  const { budget } = await capsBudgetSetData(ctx, opts);
+  return `Monthly budget set to ${formatMoney(budget.max_cost_cents)}${budget.stop_usage ? " (usage stops at the limit)" : ""}.`;
+}
+
+export async function capsInstanceData(ctx: CliContext, instance: string): Promise<InstanceCapEnvelope> {
+  const normalizedInstance = normalizeRequired(instance, "instance id");
+  return ctx.http.request<InstanceCapEnvelope>({ path: `/api/limits/instances/${encodeURIComponent(normalizedInstance)}/cap` });
+}
+
+export async function capsInstance(ctx: CliContext, instance: string): Promise<string> {
+  const normalizedInstance = normalizeRequired(instance, "instance id");
+  return formatEntityCap(await capsInstanceData(ctx, normalizedInstance), `Instance ${normalizedInstance}`);
+}
+
+export async function capsInstanceSetData(ctx: CliContext, instance: string, opts: CapSetOptions): Promise<InstanceCapEnvelope> {
+  const normalizedInstance = normalizeRequired(instance, "instance id");
+  validateCapSetOptions(opts);
+  return ctx.http.request<InstanceCapEnvelope>({
+    method: "PATCH",
+    path: `/api/limits/instances/${encodeURIComponent(normalizedInstance)}/cap`,
+    headers: { "Idempotency-Key": randomUUID() },
+    body: capBody(opts),
+  });
+}
+
+export async function capsInstanceSet(ctx: CliContext, instance: string, opts: CapSetOptions): Promise<string> {
+  const normalizedInstance = normalizeRequired(instance, "instance id");
+  const result = await capsInstanceSetData(ctx, normalizedInstance, opts);
+  return capSetMessage(`Instance ${normalizedInstance}`, result.cap, result.changed);
+}
+
+export async function capsEndUserData(ctx: CliContext, endUserId: string): Promise<EndUserCapEnvelope> {
+  const normalizedEndUserId = normalizeRequired(endUserId, "end-user id");
+  return ctx.http.request<EndUserCapEnvelope>({ path: `/api/limits/end_users/${encodeURIComponent(normalizedEndUserId)}/cap` });
+}
+
+export async function capsEndUser(ctx: CliContext, endUserId: string): Promise<string> {
+  const normalizedEndUserId = normalizeRequired(endUserId, "end-user id");
+  return formatEntityCap(await capsEndUserData(ctx, normalizedEndUserId), `End-user ${normalizedEndUserId}`);
+}
+
+export async function capsEndUserSetData(ctx: CliContext, endUserId: string, opts: CapSetOptions): Promise<EndUserCapEnvelope> {
+  const normalizedEndUserId = normalizeRequired(endUserId, "end-user id");
+  validateCapSetOptions(opts);
+  return ctx.http.request<EndUserCapEnvelope>({
+    method: "PATCH",
+    path: `/api/limits/end_users/${encodeURIComponent(normalizedEndUserId)}/cap`,
+    headers: { "Idempotency-Key": randomUUID() },
+    body: capBody(opts),
+  });
+}
+
+export async function capsEndUserSet(ctx: CliContext, endUserId: string, opts: CapSetOptions): Promise<string> {
+  const normalizedEndUserId = normalizeRequired(endUserId, "end-user id");
+  const result = await capsEndUserSetData(ctx, normalizedEndUserId, opts);
+  return capSetMessage(`End-user ${normalizedEndUserId}`, result.cap, result.changed);
+}
+
+export async function capsSeatData(ctx: CliContext, instance: string, endUserId: string): Promise<SeatCapEnvelope> {
+  const normalizedInstance = normalizeRequired(instance, "instance id");
+  const normalizedEndUserId = normalizeRequired(endUserId, "end-user id");
+  return ctx.http.request<SeatCapEnvelope>({
+    path: `/api/limits/instances/${encodeURIComponent(normalizedInstance)}/seat_cap?end_user_id=${encodeURIComponent(normalizedEndUserId)}`,
+  });
+}
+
+export async function capsSeat(ctx: CliContext, instance: string, endUserId: string): Promise<string> {
+  const normalizedInstance = normalizeRequired(instance, "instance id");
+  const normalizedEndUserId = normalizeRequired(endUserId, "end-user id");
+  return formatEntityCap(await capsSeatData(ctx, normalizedInstance, normalizedEndUserId), `Seat ${normalizedEndUserId} on ${normalizedInstance}`);
+}
+
+export async function capsSeatSetData(ctx: CliContext, instance: string, endUserId: string, opts: CapSetOptions): Promise<SeatCapEnvelope> {
+  const normalizedInstance = normalizeRequired(instance, "instance id");
+  const normalizedEndUserId = normalizeRequired(endUserId, "end-user id");
+  validateCapSetOptions(opts);
+  return ctx.http.request<SeatCapEnvelope>({
+    method: "PATCH",
+    path: `/api/limits/instances/${encodeURIComponent(normalizedInstance)}/seat_cap`,
+    headers: { "Idempotency-Key": randomUUID() },
+    body: { ...capBody(opts), end_user_id: normalizedEndUserId },
+  });
+}
+
+export async function capsSeatSet(ctx: CliContext, instance: string, endUserId: string, opts: CapSetOptions): Promise<string> {
+  const normalizedInstance = normalizeRequired(instance, "instance id");
+  const normalizedEndUserId = normalizeRequired(endUserId, "end-user id");
+  const result = await capsSeatSetData(ctx, normalizedInstance, normalizedEndUserId, opts);
+  return capSetMessage(`Seat ${normalizedEndUserId} on ${normalizedInstance}`, result.cap, result.changed);
+}
+
+function dollarsToCents(value: string | undefined): number {
+  if (value === undefined) {
+    throw new Error("Pass --amount <dollars>. Usage: dharta caps budget set --amount 250");
+  }
+  return parseDollarAmountToCents(value, "--amount");
+}
+
+export function validateBudgetSetOptions(opts: BudgetSetOptions): void {
+  dollarsToCents(opts.amount);
+  stopUsageOption(opts);
+  alertsOption(opts);
+  if (opts.alertThreshold !== undefined) {
+    parseWholeNumberInRange(opts.alertThreshold, "--alert-threshold", 0, 100);
+  }
+  for (const id of opts.recipientUserId ?? []) {
+    parsePositiveWholeNumber(id, "--recipient-user-id");
+  }
+}
+
+export function validateCapSetOptions(opts: CapSetOptions): void {
+  capBody(opts);
+}
+
+function capBody(opts: CapSetOptions): Record<string, unknown> {
+  if (opts.clear && opts.amount) throw new Error("Use either --amount or --clear, not both.");
+  if (opts.clear) return { clear: true };
+  if (!opts.amount) throw new Error("Pass --amount <dollars> or --clear.");
+  return { cap_cents: dollarsToCents(opts.amount) };
+}
+
+function parseWholeNumberInRange(value: string, flag: string, min: number, max: number): number {
+  const normalized = value.trim();
+  if (!/^\d+$/.test(normalized)) throw new Error(`${flag} must be a whole number.`);
+  const parsed = Number(normalized);
+  if (!Number.isSafeInteger(parsed) || parsed < min || parsed > max) {
+    throw new Error(`${flag} must be a whole number from ${min} to ${max}.`);
+  }
+  return parsed;
+}
+
+function parsePositiveWholeNumber(value: string, flag: string): number {
+  const normalized = value.trim();
+  if (!/^\d+$/.test(normalized)) throw new Error(`${flag} must be a whole number.`);
+  const parsed = Number(normalized);
+  if (!Number.isSafeInteger(parsed) || parsed <= 0) {
+    throw new Error(`${flag} must be a positive whole number.`);
+  }
+  return parsed;
+}
+
+function stopUsageOption(opts: BudgetSetOptions): boolean | undefined {
+  if (opts.hardStop && opts.soft) throw new Error("Use either --hard-stop or --soft, not both.");
+  if (opts.hardStop) return true;
+  if (opts.soft) return false;
+  return undefined;
+}
+
+function alertsOption(opts: BudgetSetOptions): boolean | undefined {
+  if (opts.enableAlerts && opts.disableAlerts) {
+    throw new Error("Use either --enable-alerts or --disable-alerts, not both.");
+  }
+  if (opts.enableAlerts) return true;
+  if (opts.disableAlerts) return false;
+  return undefined;
+}
+
+function formatMoney(cents: number | null): string {
+  if (cents === null) return "unlimited";
+  return `$${(cents / 100).toFixed(2)}`;
+}
+
+function formatMicros(micros: number): string {
+  return `$${(micros / 100_000_000).toFixed(4)}`;
+}
+
+function formatEntityCap(result: { spend_micros: number; cap: EntityCap | null }, label: string): string {
+  return [
+    `${label}`,
+    `Spend this period: ${formatMicros(result.spend_micros)}`,
+    `Cap: ${result.cap ? formatMoney(result.cap.cap_cents) : "none"}`,
+  ].join("\n");
+}
+
+function capSetMessage(label: string, cap: EntityCap | null, changed: boolean | undefined): string {
+  const state = cap ? formatMoney(cap.cap_cents) : "cleared";
+  return `${label} cap ${state}${changed === false ? " (unchanged)" : ""}.`;
+}
+
+function normalizeRequired(value: string, label: string): string {
+  const normalized = value.trim();
+  if (!normalized) {
+    throw new Error(`${label} cannot be blank.`);
+  }
+  return normalized;
+}

package/src/commands/create.ts

@@ -0,0 +1,114 @@
+import { promises as fs } from "node:fs";
+import * as path from "node:path";
+import { renderManifest } from "../manifest.js";
+import { scaffoldTemplate } from "../scaffold.js";
+import { deriveSlug } from "../agent.js";
+import { normalizeNonBlank } from "../validators.js";
+import { DEFAULT_CREATE_HARNESS, hasAgentMarker, parseHarnessType, type HarnessType } from "../harnesses.js";
+
+// `dharta create [path]` (RFC 0024): bring a brand-new agent into existence -
+// lay down a starter template + a default (deploy-off) dharta.toml. It does ONE
+// thing: scaffold. Configuration - the deploy gate, delivery method, rename,
+// git/github wiring - is `dharta setup`'s job. One agent per folder: create
+// refuses a folder that already holds an agent (pointing at setup), and setup
+// refuses one that doesn't (pointing back here), so the two never overlap.
+
+export interface CreateOptions {
+  cwd?: string;
+  name?: string;
+  template?: string; // starter template (default "blank")
+  harness?: string; // supported harness type (default "claude-code")
+  harnessVersion?: string; // optional exact/range pin; omitted = curated default
+  baseUrl: string; // template source (control plane; falls back to bundled)
+  fetchImpl?: typeof fetch;
+  log?: (line: string) => void;
+}
+
+export interface CreateResult {
+  folder: string; // relative to cwd
+  name: string;
+  template: string;
+  harness: HarnessType;
+  harnessVersion?: string;
+  instructionFile: "CLAUDE.md" | "AGENTS.md";
+  manifestPath: string; // absolute
+  files: string[]; // everything written, relative to the folder
+}
+
+export async function create(pathArg: string | undefined, opts: CreateOptions): Promise<CreateResult> {
+  const cwd = path.resolve(opts.cwd ?? ".");
+  const log = opts.log ?? ((line: string) => console.error(line));
+  const pathInput = pathArg === undefined ? undefined : normalizeNonBlank(pathArg, "path");
+  const targetDir = path.resolve(cwd, pathInput ?? ".");
+  const rel = path.relative(cwd, targetDir) || ".";
+  const name = opts.name === undefined ? deriveSlug(path.basename(targetDir)) : normalizeNonBlank(opts.name, "--name");
+  const template = opts.template === undefined ? undefined : normalizeNonBlank(opts.template, "--template");
+  const harness = parseHarnessType(opts.harness, "--harness") ?? DEFAULT_CREATE_HARNESS;
+  const harnessVersion = opts.harnessVersion === undefined
+    ? undefined
+    : normalizeNonBlank(opts.harnessVersion, "--harness-version");
+  // Echo what the user typed (a clean `lifecoach`) in messages rather than the
+  // resolved ../../ path when they pass an absolute or distant target.
+  const shown = pathInput && pathInput !== "." ? pathInput : null;
+  const here = shown ?? "this folder";
+  const at = shown ? ` ${shown}` : "";
+
+  await validateTargetDirectory(targetDir, here);
+
+  // One agent per folder: a marker means an agent already lives here - that's
+  // setup's job, not create's. Refuse rather than scaffold over it.
+  if (hasAgentMarker(targetDir)) {
+    throw new Error(
+      `An agent already exists in ${here}. Configure it with \`dharta setup${at}\` instead.`,
+    );
+  }
+
+  // Scaffold the template (CLAUDE.md / .claude / .gitignore - never dharta.toml,
+  // which we own below).
+  const scaffold = await scaffoldTemplate(targetDir, {
+    template,
+    harness,
+    baseUrl: opts.baseUrl,
+    fetchImpl: opts.fetchImpl,
+    log,
+  });
+
+  // Write the self-documenting manifest. A brand-new agent is deploy = false
+  // (the D6 fail-safe); `dharta setup --enable` flips the gate when you're ready.
+  const manifestPath = path.join(targetDir, "dharta.toml");
+  await fs.writeFile(manifestPath, renderManifest({ name, deploy: false, harness, harnessVersion }));
+
+  const files = [...scaffold.files, "dharta.toml"];
+  log(
+    `Created ${harness} agent '${name}' in ${here} from the '${scaffold.template}' template ` +
+      `(${files.join(", ")}).`,
+  );
+  log(`Next: edit ${scaffold.instructionFile}, chat locally with \`dharta dev${at}\`, then \`dharta setup${at}\` to set the deploy gate + delivery method.`);
+
+  return {
+    folder: rel,
+    name,
+    template: scaffold.template,
+    harness,
+    harnessVersion,
+    instructionFile: scaffold.instructionFile,
+    manifestPath,
+    files,
+  };
+}
+
+async function validateTargetDirectory(targetDir: string, label: string): Promise<void> {
+  try {
+    const stat = await fs.stat(targetDir);
+    if (!stat.isDirectory()) {
+      throw new Error(`Cannot create agent in ${label}: expected a directory, got a file.`);
+    }
+  } catch (error) {
+    const code = (error as NodeJS.ErrnoException).code;
+    if (code === "ENOENT") return;
+    if (code === "ENOTDIR") {
+      throw new Error(`Cannot create agent in ${label}: a parent path is not a directory.`);
+    }
+    throw error;
+  }
+}