@dharta/cli 0.6.77

package/src/commands/open.ts

@@ -0,0 +1,173 @@
+// `dharta open [target]` (RFC 0013 CLI-5): open the hosted chat page,
+// the agent console, or account handoff pages. URLs come from the
+// control plane so the CLI never re-derives the host scheme.
+
+import type { CliContext } from "../context.js";
+import { openBrowser } from "../browser.js";
+import { inferAgentSlug, type AgentInferOptions } from "../agent.js";
+
+export interface OpenOptions extends AgentInferOptions {
+  openBrowserImpl?: (url: string) => Promise<boolean>;
+}
+
+interface ProjectShow {
+  agent_url: string;
+  console_url: string;
+  live_version: number | null;
+  project: { slug: string };
+}
+
+export interface OpenData {
+  slug?: string;
+  target: "agent" | "console" | "billing" | "security" | "api-keys" | "model-keys" | "webhooks" | "connected-accounts";
+  url: string;
+  // null until the first deploy; the agent target falls back to the
+  // console rather than opening a dead chat page.
+  live_version: number | null;
+  redirected_to_console: boolean;
+}
+
+const HANDOFF_TARGETS = {
+  billing: "/billing",
+  security: "/account/security",
+  "api-keys": "/api_keys",
+  "model-keys": "/model_keys",
+  webhooks: "/webhook_endpoints",
+  "connected-accounts": "/account/connected_accounts",
+} as const;
+
+export const OPEN_TARGETS_HELP = ["console", ...Object.keys(HANDOFF_TARGETS)].join(", ");
+const OPEN_TARGETS = ["console", ...Object.keys(HANDOFF_TARGETS)];
+
+export function isHandoffTarget(target: string | undefined): target is keyof typeof HANDOFF_TARGETS {
+  return target !== undefined && target in HANDOFF_TARGETS;
+}
+
+export function normalizeOpenTarget(target: string | undefined): string | undefined {
+  return target === undefined ? undefined : target.trim();
+}
+
+export function validateOpenTarget(target: string | undefined): void {
+  const normalizedTarget = normalizeOpenTarget(target);
+  if (target !== undefined && normalizedTarget === "") {
+    throw new Error("target cannot be blank.");
+  }
+  if (normalizedTarget !== undefined && normalizedTarget !== "console" && !isHandoffTarget(normalizedTarget)) {
+    const suggestion = closestTarget(normalizedTarget);
+    throw new Error(
+      `Unknown target '${normalizedTarget}'. Use one of: ${OPEN_TARGETS_HELP}.` +
+        (suggestion ? ` Did you mean '${suggestion}'?` : ""),
+    );
+  }
+}
+
+function closestTarget(input: string): string | null {
+  let best: { target: string; distance: number } | null = null;
+  for (const target of OPEN_TARGETS) {
+    const distance = levenshtein(input, target);
+    if (distance <= 2 && (!best || distance < best.distance)) {
+      best = { target, distance };
+    }
+  }
+  return best?.target ?? null;
+}
+
+function levenshtein(a: string, b: string): number {
+  const previous = Array.from({ length: b.length + 1 }, (_, i) => i);
+  const current = Array.from({ length: b.length + 1 }, () => 0);
+  for (let i = 1; i <= a.length; i += 1) {
+    current[0] = i;
+    for (let j = 1; j <= b.length; j += 1) {
+      const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+      current[j] = Math.min(current[j - 1] + 1, previous[j] + 1, previous[j - 1] + cost);
+    }
+    previous.splice(0, previous.length, ...current);
+  }
+  return previous[b.length];
+}
+
+export function openHandoffData(
+  baseUrl: string,
+  target: keyof typeof HANDOFF_TARGETS,
+): OpenData {
+  return {
+    target,
+    url: absoluteUrl(baseUrl, HANDOFF_TARGETS[target]),
+    live_version: null,
+    redirected_to_console: false,
+  };
+}
+
+export async function openHandoff(
+  baseUrl: string,
+  target: keyof typeof HANDOFF_TARGETS,
+  opts: Pick<OpenOptions, "openBrowserImpl"> = {},
+): Promise<string> {
+  const data = openHandoffData(baseUrl, target);
+  const opened = await (opts.openBrowserImpl ?? openBrowser)(data.url);
+  return opened ? `Opening ${data.url}` : `Open this in your browser: ${data.url}`;
+}
+
+// Resolve the URL without opening anything - the --json path prints
+// this object instead of launching a browser.
+export async function openData(
+  ctx: CliContext,
+  target: string | undefined,
+  opts: AgentInferOptions = {},
+): Promise<OpenData> {
+  const normalizedTarget = normalizeOpenTarget(target);
+  if (isHandoffTarget(normalizedTarget)) {
+    return openHandoffData(ctx.baseUrl, normalizedTarget);
+  }
+  validateOpenTarget(normalizedTarget);
+  if (normalizedTarget === "console" && !hasAgentSelector(opts)) {
+    return {
+      target: "console",
+      url: absoluteUrl(ctx.baseUrl, "/agents"),
+      live_version: null,
+      redirected_to_console: false,
+    };
+  }
+  const slug = await inferAgentSlug(opts);
+  const shown = await ctx.http.request<ProjectShow>({
+    path: `/api/agents/${encodeURIComponent(slug)}`,
+  });
+  const wantsAgent = normalizedTarget !== "console";
+  const noRelease = shown.live_version == null;
+  const redirected = wantsAgent && noRelease;
+  return {
+    slug,
+    target: wantsAgent && !redirected ? "agent" : "console",
+    url: wantsAgent && !redirected ? shown.agent_url : shown.console_url,
+    live_version: shown.live_version ?? null,
+    redirected_to_console: redirected,
+  };
+}
+
+export async function open(
+  ctx: CliContext,
+  target: string | undefined,
+  opts: OpenOptions = {},
+): Promise<string> {
+  const data = await openData(ctx, target, opts);
+  const opened = await (opts.openBrowserImpl ?? openBrowser)(data.url);
+  const prefix = data.redirected_to_console
+    ? `Nothing is deployed on ${data.slug} yet - deploy with: git push dharta main\n` +
+      "Opening the agent console instead.\n"
+    : "";
+  return prefix + (opened ? `Opening ${data.url}` : `Open this in your browser: ${data.url}`);
+}
+
+function hasAgentSelector(opts: AgentInferOptions): boolean {
+  return (
+    opts.agent !== undefined ||
+    opts.project !== undefined ||
+    opts.path !== undefined ||
+    opts.dir !== undefined ||
+    (opts.env ?? process.env).DHARTA_PROJECT !== undefined
+  );
+}
+
+function absoluteUrl(baseUrl: string, path: string): string {
+  return `${baseUrl.replace(/\/+$/, "")}${path}`;
+}

package/src/commands/parity.ts

@@ -0,0 +1,96 @@
+// `dharta dev --release vN` / `--env remote` (RFC 0013 CLI-10): two
+// orthogonal parity axes. --release runs the exact built tree prod
+// serves (transcript-driven debugging: read the transcript with
+// `dharta sessions show`, replay against the same code locally);
+// --env remote binds prod env vars instead of .env. Honest limits:
+// parity of code + config, not infrastructure.
+
+import { promises as fs } from "node:fs";
+import { randomUUID } from "node:crypto";
+import * as os from "node:os";
+import * as path from "node:path";
+import { spawn } from "node:child_process";
+import type { CliContext } from "../context.js";
+import { inferAgentSlug, type AgentInferOptions } from "../agent.js";
+import { parseReleaseVersion } from "../validators.js";
+
+// Download + extract the release archive; returns the extracted dir.
+export async function prepareReleaseDir(
+  ctx: CliContext,
+  releaseVersion: string,
+  opts: AgentInferOptions & { fetchImpl?: typeof fetch } = {},
+): Promise<{ dir: string; version: number; commitSha: string }> {
+  const version = parseReleaseVersion(releaseVersion, "--release");
+  const slug = await inferAgentSlug(opts);
+  const meta = await ctx.http.request<{ version: number; commit_sha: string; url: string }>({
+    path: `/api/agents/${encodeURIComponent(slug)}/releases/${encodeURIComponent(version)}/archive`,
+  });
+
+  const fetchImpl = (opts.fetchImpl ?? globalThis.fetch).bind(globalThis);
+  const res = await fetchReleaseArchive(meta.url, slug, fetchImpl);
+  if (!res.ok) {
+    throw new Error(
+      `Could not download the release archive (HTTP ${res.status}). ` +
+        `Check the version with \`dharta agent releases ${slug}\` and retry.`,
+    );
+  }
+  const bytes = Buffer.from(await res.arrayBuffer());
+
+  const dir = await fs.mkdtemp(path.join(os.tmpdir(), `karta-${slug}-v${meta.version}-`));
+  const tarball = path.join(dir, "release.tar.gz");
+  await fs.writeFile(tarball, bytes);
+  await untar(tarball, dir);
+  await fs.rm(tarball, { force: true });
+
+  return { dir, version: meta.version, commitSha: meta.commit_sha };
+}
+
+// Fetch prod env bindings for --env remote. Secrets ride the same D6
+// rails as `dharta env pull --include-secrets`.
+export async function fetchRemoteEnv(
+  ctx: CliContext,
+  opts: AgentInferOptions & { includeSecrets?: boolean } = {},
+): Promise<{ values: Record<string, string>; withheld: string[] }> {
+  const slug = await inferAgentSlug(opts);
+  const body = await ctx.http.request<{
+    env: Array<{ name: string; secret: boolean; value?: string; withheld?: boolean }>;
+  }>({
+    method: "POST",
+    path: `/api/agents/${encodeURIComponent(slug)}/env/pull`,
+    headers: { "Idempotency-Key": randomUUID() },
+    body: { include_secrets: !!opts.includeSecrets },
+  });
+
+  const values: Record<string, string> = {};
+  const withheld: string[] = [];
+  for (const entry of body.env) {
+    if (entry.withheld) withheld.push(entry.name);
+    else values[entry.name] = entry.value ?? "";
+  }
+  return { values, withheld };
+}
+
+async function fetchReleaseArchive(url: string, slug: string, fetchImpl: typeof fetch): Promise<Response> {
+  try {
+    return await fetchImpl(url);
+  } catch (error) {
+    throw new Error(
+      `Could not download the release archive from ${url}: ${(error as Error).message}. ` +
+        `Check the version with \`dharta agent releases ${slug}\` and retry.`,
+    );
+  }
+}
+
+function untar(tarball: string, dest: string): Promise<void> {
+  return new Promise((resolve, reject) => {
+    const proc = spawn("tar", ["-xzf", tarball, "-C", dest], { stdio: "ignore" });
+    proc.on("error", () =>
+      reject(new Error("Could not extract the release archive (is `tar` installed?).")),
+    );
+    proc.on("close", (code) =>
+      code === 0
+        ? resolve()
+        : reject(new Error(`tar exited ${code} extracting the release archive.`)),
+    );
+  });
+}

package/src/commands/rollback.ts

@@ -0,0 +1,45 @@
+// Re-deploy a previous release by pointer flip. (Forward deploys are
+// `dharta deploy` / `git push dharta`; this is the rollback-only path.)
+import type { CliContext } from "../context.js";
+import { randomUUID } from "node:crypto";
+import { validateAgentSlug } from "../agent.js";
+
+export interface RollbackResponse {
+  agent: { id: string; slug: string; name: string };
+  release: { id: string; version: number; status: string; commit_sha: string };
+  previous_release: { id: string; version: number; status: string } | null;
+}
+
+export async function rollbackData(
+  ctx: CliContext,
+  slug: string,
+  toVersion: number,
+): Promise<RollbackResponse> {
+  const normalizedSlug = validateAgentSlug(slug, "agent slug");
+  const normalizedVersion = normalizeRollbackVersion(toVersion);
+  return ctx.http.request<RollbackResponse>({
+    method: "POST",
+    path: `/api/agents/${encodeURIComponent(normalizedSlug)}/rollback`,
+    headers: { "Idempotency-Key": randomUUID() },
+    body: { to_version: normalizedVersion },
+  });
+}
+
+export async function rollback(
+  ctx: CliContext,
+  slug: string,
+  toVersion: number,
+): Promise<string> {
+  const res = await rollbackData(ctx, slug, toVersion);
+  const prev = res.previous_release
+    ? ` (from v${res.previous_release.version})`
+    : "";
+  return `Rolled back ${res.agent.slug} to v${res.release.version}${prev}.`;
+}
+
+function normalizeRollbackVersion(toVersion: number): number {
+  if (!Number.isSafeInteger(toVersion) || toVersion <= 0) {
+    throw new Error("version must be a positive whole number.");
+  }
+  return toVersion;
+}

package/src/commands/schedules.ts

@@ -0,0 +1,290 @@
+import { randomUUID } from "node:crypto";
+import { inferAgentSlug, type AgentInferOptions } from "../agent.js";
+import type { CliContext } from "../context.js";
+import { parseDollarAmountToCents } from "../money.js";
+import { fmtTs, table } from "../output.js";
+import { normalizeNonBlank, normalizeTimezone, parsePositiveInteger, parseReleaseVersion } from "../validators.js";
+
+export interface Schedule {
+  id: number;
+  cron: string;
+  timezone: string;
+  initial_message: string;
+  release_version: number | null;
+  budget_cents: number | null;
+  end_user_id: string | null;
+  enabled: boolean;
+  next_fire_at: string | null;
+  last_fired_at: string | null;
+  created_at: string;
+  updated_at: string;
+}
+
+interface ListEnvelope<T> {
+  data: T[];
+}
+
+interface ScheduleEnvelope {
+  schedule: Schedule;
+  changed?: boolean;
+  queued?: boolean;
+}
+
+export interface ScheduleCreateOptions extends AgentInferOptions {
+  cron?: string;
+  timezone?: string;
+  message?: string;
+  budget?: string;
+  budgetCents?: string;
+  releaseVersion?: string;
+  endUserId?: string;
+  runNow?: boolean;
+}
+
+export async function schedulesListData(ctx: CliContext, opts: AgentInferOptions): Promise<{ slug: string; data: Schedule[] }> {
+  const slug = await inferAgentSlug(opts);
+  const res = await ctx.http.request<ListEnvelope<Schedule>>({
+    path: `/api/agents/${encodeURIComponent(slug)}/schedules`,
+  });
+  return { slug, data: res.data };
+}
+
+export async function schedulesList(ctx: CliContext, opts: AgentInferOptions): Promise<string> {
+  const { slug, data } = await schedulesListData(ctx, opts);
+  if (data.length === 0) return `No schedules for ${slug}. Create one with: dharta schedules create --agent ${slug} --cron '0 9 * * *' --message 'Daily check-in'`;
+  return table(data.map((schedule) => ({
+    id: String(schedule.id),
+    state: schedule.enabled ? "enabled" : "paused",
+    cron: schedule.cron,
+    timezone: schedule.timezone,
+    next: fmtTs(schedule.next_fire_at),
+    budget: formatBudget(schedule.budget_cents),
+  })));
+}
+
+export async function schedulesCreateData(
+  ctx: CliContext,
+  opts: ScheduleCreateOptions,
+): Promise<{ slug: string } & ScheduleEnvelope> {
+  validateSchedulesCreateInput(opts);
+  const cron = opts.cron as string;
+  const message = opts.message as string;
+  const slug = await inferAgentSlug(opts);
+  const body: Record<string, unknown> = {
+    cron: normalizeRequired(cron, "--cron"),
+    timezone: opts.timezone === undefined ? "UTC" : normalizeTimezone(opts.timezone, "--timezone"),
+    initial_message: normalizeRequired(message, "--message"),
+  };
+  if (opts.budget !== undefined && opts.budgetCents !== undefined) {
+    throw new Error("Use either --budget or --budget-cents, not both.");
+  }
+  if (opts.budget !== undefined) body.budget_cents = parseDollarAmountToCents(opts.budget, "--budget");
+  if (opts.budgetCents !== undefined) body.budget_cents = parsePositiveWholeNumber(opts.budgetCents, "--budget-cents");
+  if (opts.releaseVersion !== undefined) body.release_version = parseReleaseVersion(opts.releaseVersion, "--release-version");
+  if (opts.endUserId !== undefined) body.end_user_id = normalizeRequired(opts.endUserId, "--end-user-id");
+  const res = await ctx.http.request<ScheduleEnvelope>({
+    method: "POST",
+    path: `/api/agents/${encodeURIComponent(slug)}/schedules`,
+    headers: idempotencyHeader(),
+    body: { schedule: body },
+  });
+  if (opts.runNow) {
+    const run = await runScheduleNow(ctx, slug, String(res.schedule.id));
+    return { slug, ...res, queued: run.queued ?? true };
+  }
+  return { slug, ...res };
+}
+
+export async function schedulesCreate(ctx: CliContext, opts: ScheduleCreateOptions): Promise<string> {
+  const res = await schedulesCreateData(ctx, opts);
+  return `Created schedule ${res.schedule.id} for ${res.slug}${res.queued ? " and queued one run" : ""}.`;
+}
+
+export function validateSchedulesCreateInput(opts: ScheduleCreateOptions): void {
+  const missing = [
+    opts.cron === undefined ? "--cron <expr>" : null,
+    opts.message === undefined ? "--message <text>" : null,
+  ].filter((flag): flag is string => flag !== null);
+  if (missing.length > 0) {
+    throw new Error(
+      `Pass ${formatMissingFlags(missing)}. ` +
+        "Usage: dharta schedules create --cron '0 9 * * *' --message 'Daily check-in'",
+    );
+  }
+  const cron = opts.cron as string;
+  const message = opts.message as string;
+  validateCron(cron);
+  if (opts.timezone !== undefined) normalizeTimezone(opts.timezone, "--timezone");
+  normalizeRequired(message, "--message");
+  if (opts.budget !== undefined && opts.budgetCents !== undefined) {
+    throw new Error("Use either --budget or --budget-cents, not both.");
+  }
+  if (opts.budget !== undefined) parseDollarAmountToCents(opts.budget, "--budget");
+  if (opts.budgetCents !== undefined) parsePositiveWholeNumber(opts.budgetCents, "--budget-cents");
+  if (opts.releaseVersion !== undefined) parseReleaseVersion(opts.releaseVersion, "--release-version");
+  if (opts.endUserId !== undefined) normalizeRequired(opts.endUserId, "--end-user-id");
+}
+
+function formatMissingFlags(flags: string[]): string {
+  return flags.length === 1 ? flags[0] : `${flags.slice(0, -1).join(", ")} and ${flags[flags.length - 1]}`;
+}
+
+function validateCron(value: string): void {
+  const cron = normalizeRequired(value, "--cron");
+  const fields = cron.split(/\s+/);
+  if (fields.length !== 5 || fields.some((field) => field.length === 0)) {
+    throw new Error("--cron must be a standard 5-field cron expression, e.g. '0 9 * * *'.");
+  }
+  fields.forEach((field, index) => validateCronField(field, CRON_FIELD_SPECS[index]));
+}
+
+const CRON_FIELD_SPECS = [
+  { name: "minute", min: 0, max: 59, names: {} },
+  { name: "hour", min: 0, max: 23, names: {} },
+  { name: "day-of-month", min: 1, max: 31, names: {} },
+  {
+    name: "month",
+    min: 1,
+    max: 12,
+    names: { jan: 1, feb: 2, mar: 3, apr: 4, may: 5, jun: 6, jul: 7, aug: 8, sep: 9, oct: 10, nov: 11, dec: 12 },
+  },
+  {
+    name: "day-of-week",
+    min: 0,
+    max: 7,
+    names: { sun: 0, mon: 1, tue: 2, wed: 3, thu: 4, fri: 5, sat: 6 },
+  },
+] as const;
+
+type CronFieldSpec = (typeof CRON_FIELD_SPECS)[number];
+
+function validateCronField(field: string, spec: CronFieldSpec): void {
+  for (const item of field.split(",")) {
+    if (!item) throw unsupportedCronField(spec);
+    const [base, step, extra] = item.split("/");
+    if (extra !== undefined || !base) throw unsupportedCronField(spec);
+    if (step !== undefined && !/^[1-9]\d*$/.test(step)) {
+      throw new Error(`--cron ${spec.name} field step must be a positive whole number.`);
+    }
+    if (base === "*") continue;
+
+    const [start, end, extraRange] = base.split("-");
+    if (extraRange !== undefined || !start) throw unsupportedCronField(spec);
+    if (end === undefined) {
+      parseCronToken(start, spec);
+      continue;
+    }
+    if (!end) throw unsupportedCronField(spec);
+    const rangeStart = parseCronToken(start, spec);
+    const rangeEnd = parseCronToken(end, spec);
+    if (rangeStart > rangeEnd) {
+      throw new Error(`--cron ${spec.name} field range must start before it ends.`);
+    }
+  }
+}
+
+function parseCronToken(token: string, spec: CronFieldSpec): number {
+  const normalized = token.toLowerCase();
+  const named = (spec.names as Record<string, number>)[normalized];
+  if (named !== undefined) return named;
+  if (!/^\d+$/.test(token)) throw unsupportedCronField(spec);
+  const parsed = Number(token);
+  if (parsed < spec.min || parsed > spec.max) {
+    throw new Error(`--cron ${spec.name} field must be ${spec.min}-${spec.max}.`);
+  }
+  return parsed;
+}
+
+function unsupportedCronField(spec: CronFieldSpec): Error {
+  return new Error(`--cron ${spec.name} field is not supported. Use numbers, *, ranges, lists, and steps.`);
+}
+
+export async function schedulesActionData(
+  ctx: CliContext,
+  id: string,
+  action: "pause" | "resume" | "run",
+  opts: AgentInferOptions,
+): Promise<{ slug: string } & ScheduleEnvelope> {
+  const normalizedId = normalizeScheduleId(id);
+  const slug = await inferAgentSlug(opts);
+  const res = action === "run"
+    ? await runScheduleNow(ctx, slug, normalizedId)
+    : await ctx.http.request<ScheduleEnvelope>({
+      method: "POST",
+      path: `/api/agents/${encodeURIComponent(slug)}/schedules/${encodeURIComponent(normalizedId)}/${action}`,
+      headers: idempotencyHeader(),
+    });
+  return { slug, ...res };
+}
+
+export async function schedulesAction(
+  ctx: CliContext,
+  id: string,
+  action: "pause" | "resume" | "run",
+  opts: AgentInferOptions,
+): Promise<string> {
+  const res = await schedulesActionData(ctx, id, action, opts);
+  if (action === "run") return `Queued schedule ${res.schedule.id} for ${res.slug}.`;
+  return `${action === "pause" ? "Paused" : "Resumed"} schedule ${res.schedule.id} for ${res.slug}${res.changed ? "" : " (unchanged)"}.`;
+}
+
+export async function schedulesDeleteData(
+  ctx: CliContext,
+  id: string,
+  opts: AgentInferOptions,
+): Promise<{ slug: string; id: string; deleted: boolean }> {
+  const normalizedId = normalizeScheduleId(id);
+  const slug = await inferAgentSlug(opts);
+  await ctx.http.request<void>({
+    method: "DELETE",
+    path: `/api/agents/${encodeURIComponent(slug)}/schedules/${encodeURIComponent(normalizedId)}`,
+    headers: idempotencyHeader(),
+  });
+  return { slug, id: normalizedId, deleted: true };
+}
+
+export async function schedulesDelete(ctx: CliContext, id: string, opts: AgentInferOptions): Promise<string> {
+  const res = await schedulesDeleteData(ctx, id, opts);
+  return `Deleted schedule ${res.id} for ${res.slug}.`;
+}
+
+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 formatBudget(cents: number | null): string {
+  if (cents === null) return "—";
+  return `$${(cents / 100).toFixed(2)}`;
+}
+
+function idempotencyHeader(): Record<string, string> {
+  return { "Idempotency-Key": randomUUID() };
+}
+
+function runScheduleNow(ctx: CliContext, slug: string, id: string): Promise<ScheduleEnvelope> {
+  return ctx.http.request<ScheduleEnvelope>({
+    method: "POST",
+    path: `/api/agents/${encodeURIComponent(slug)}/schedules/${encodeURIComponent(id)}/run`,
+    headers: idempotencyHeader(),
+  });
+}
+
+function normalizeRequired(value: string, flag: string): string {
+  const normalized = value.trim();
+  if (!normalized) {
+    throw new Error(`${flag} cannot be blank.`);
+  }
+  return normalized;
+}
+
+function normalizeScheduleId(id: string): string {
+  const normalized = normalizeNonBlank(id, "Schedule id");
+  parsePositiveInteger(normalized, "Schedule id");
+  return normalized;
+}

package/src/commands/scopes.ts

@@ -0,0 +1,22 @@
+export const SENSITIVE_API_KEY_SCOPES = new Set([
+  "env:secrets:read",
+  "source_archives:read",
+  "workspace_tokens:create",
+  "workspace:read",
+  "audit_log:export",
+  "members:invite",
+  "members:write",
+  "members:owner_role:write",
+  "agents:delete",
+  "keys:write",
+  "model_keys:write",
+]);
+
+export function formatScopes(scopes: readonly string[], separator = ", "): string {
+  return scopes.join(separator);
+}
+
+export function formatApiKeyExpiry(expiresAt: string | null | undefined): string {
+  const normalized = expiresAt?.trim();
+  return normalized ? normalized : "none - revocable on the dashboard keys page";
+}