@dharta/cli 0.6.77

package/src/commands/env.ts

@@ -0,0 +1,369 @@
+// `dharta env list|set|unset|pull|diff` (RFC 0013 CLI-8): the prod half
+// of declare-or-bind. Declarations live in dharta.toml [env]; .env binds
+// locally; these verbs manage the prod bindings and report drift.
+
+import { promises as fs } from "node:fs";
+import * as path from "node:path";
+import { randomUUID } from "node:crypto";
+import TOML from "@iarna/toml";
+import type { CliContext } from "../context.js";
+import { inferAgentSlug, validateAgentSelectorOptions, type AgentInferOptions } from "../agent.js";
+import { table } from "../output.js";
+import { normalizeNonBlank } from "../validators.js";
+
+export interface EnvOptions extends AgentInferOptions {
+  force?: boolean; // pull: overwrite an existing .env
+  includeSecrets?: boolean; // pull: fetch secret-marked values (env:secrets:read)
+  secret?: boolean; // set: mark the value secret
+  reveal?: boolean; // list: print full values instead of masking them
+}
+
+// Env values routinely hold credentials the setter never flagged `--secret`
+// (a GitHub PAT, a webhook signing key). `list` therefore masks EVERY value by
+// default - a routine listing must never dump a live secret to the terminal or
+// CI logs. A short tail is kept so an operator can still tell two bindings
+// apart (matching how `whoami`/model keys show only a tail); `--reveal` prints
+// the full value for the rare time it is actually needed.
+export function maskEnvValue(v: { secret: boolean; value?: string | null }, reveal: boolean): string {
+  if (reveal) return v.value ?? "";
+  if (v.secret) return "•••••• (secret)";
+  const val = v.value ?? "";
+  if (val === "") return "";
+  return val.length > 4 ? `…${val.slice(-4)}` : "••••";
+}
+
+export interface EnvEntry {
+  name: string;
+  secret: boolean;
+  value?: string;
+  withheld?: boolean;
+  updated_at?: string;
+}
+
+export async function envListData(
+  ctx: CliContext,
+  opts: EnvOptions = {},
+): Promise<{ slug: string; env: EnvEntry[] }> {
+  const slug = await inferAgentSlug(opts);
+  const body = await ctx.http.request<{ env: EnvEntry[] }>({
+    path: `/api/agents/${encodeURIComponent(slug)}/env`,
+  });
+  return { slug, env: body.env };
+}
+
+export async function envList(ctx: CliContext, opts: EnvOptions = {}): Promise<string> {
+  const { slug, env } = await envListData(ctx, opts);
+  if (env.length === 0) {
+    return `No env vars set for ${slug}. Bind one with: dharta env set NAME=value`;
+  }
+  return table(
+    env.map((v) => ({
+      name: v.name,
+      value: maskEnvValue(v, opts.reveal === true),
+      updated: v.updated_at ?? "",
+    })),
+  );
+}
+
+export async function envSetData(
+  ctx: CliContext,
+  assignment: string,
+  opts: EnvOptions = {},
+): Promise<{ slug: string; name: string; secret: boolean }> {
+  const { name, value } = parseEnvAssignment(assignment);
+  const slug = await inferAgentSlug(opts);
+  const body: Record<string, unknown> = { value };
+  if (opts.secret) body.secret = true;
+  await ctx.http.request({
+    method: "PUT",
+    path: `/api/agents/${encodeURIComponent(slug)}/env/${encodeURIComponent(name)}`,
+    body,
+    headers: { "Idempotency-Key": randomUUID() },
+  });
+  return { slug, name, secret: !!opts.secret };
+}
+
+export function validateEnvAssignment(assignment: string): void {
+  parseEnvAssignment(assignment);
+}
+
+export function validateEnvName(name: string): void {
+  normalizeEnvName(name);
+}
+
+function parseEnvAssignment(assignment: string): { name: string; value: string } {
+  const eq = assignment.indexOf("=");
+  if (eq <= 0) {
+    throw new Error("Usage: dharta env set NAME=value [--secret]");
+  }
+  const name = normalizeEnvName(assignment.slice(0, eq));
+  const value = assignment.slice(eq + 1);
+  return { name, value };
+}
+
+export async function envSet(
+  ctx: CliContext,
+  assignment: string,
+  opts: EnvOptions = {},
+): Promise<string> {
+  const { slug, name, secret } = await envSetData(ctx, assignment, opts);
+  return (
+    `Set ${name}${secret ? " (secret)" : ""} on ${slug}. ` +
+    "The next build picks it up; redeploy with git push dharta main if needed."
+  );
+}
+
+export async function envUnsetData(
+  ctx: CliContext,
+  name: string,
+  opts: EnvOptions = {},
+): Promise<{ slug: string; name: string; removed: boolean }> {
+  const normalizedName = normalizeEnvName(name);
+  const slug = await inferAgentSlug(opts);
+  await ctx.http.request({
+    method: "DELETE",
+    path: `/api/agents/${encodeURIComponent(slug)}/env/${encodeURIComponent(normalizedName)}`,
+    headers: { "Idempotency-Key": randomUUID() },
+  });
+  return { slug, name: normalizedName, removed: true };
+}
+
+export async function envUnset(
+  ctx: CliContext,
+  name: string,
+  opts: EnvOptions = {},
+): Promise<string> {
+  const { slug, name: removed } = await envUnsetData(ctx, name, opts);
+  return `Removed ${removed} from ${slug}.`;
+}
+
+// Hydrate .env from prod (D6): secret-marked values are excluded unless
+// --include-secrets (bounded env:secrets:read key);
+// every pull is audited server-side.
+export async function envPullData(
+  ctx: CliContext,
+  opts: EnvOptions = {},
+): Promise<{ slug: string; path: string; written: string[]; withheld: string[] }> {
+  const dir = path.resolve(opts.dir ?? process.cwd());
+  const target = path.join(dir, ".env");
+
+  await validateEnvPullOptions(opts);
+  const slug = await inferAgentSlug(opts);
+
+  const body = await ctx.http.request<{ env: EnvEntry[] }>({
+    method: "POST",
+    path: `/api/agents/${encodeURIComponent(slug)}/env/pull`,
+    body: { include_secrets: !!opts.includeSecrets },
+    headers: { "Idempotency-Key": randomUUID() },
+  });
+
+  const bound = body.env.filter((v) => !v.withheld);
+  const lines = bound.map((v) => `${v.name}=${quoteIfNeeded(v.value ?? "")}`);
+  const withheld = body.env.filter((v) => v.withheld).map((v) => v.name);
+
+  await writeEnvFile(
+    target,
+    `# Pulled from ${slug} by dharta env pull - do not commit.\n${lines.join("\n")}\n`,
+  );
+
+  return { slug, path: target, written: bound.map((v) => v.name), withheld };
+}
+
+export async function envPull(ctx: CliContext, opts: EnvOptions = {}): Promise<string> {
+  const res = await envPullData(ctx, opts);
+  const n = res.written.length;
+  let out = `Wrote ${n} value${n === 1 ? "" : "s"} to ${res.path}.`;
+  if (res.withheld.length > 0) {
+    out +=
+      `\n${res.withheld.length} secret value${res.withheld.length === 1 ? "" : "s"} withheld (${res.withheld.join(", ")}). ` +
+      "Re-run with --include-secrets using a key with env:secrets:read to fetch them (audited).";
+  }
+  return out;
+}
+
+export type DriftKind =
+  | "prod-only"
+  | "value-differs"
+  | "secret"
+  | "local-only"
+  | "declared-only";
+
+export interface DriftEntry {
+  kind: DriftKind;
+  name: string;
+  secret?: boolean;
+}
+
+// Local (.env) vs prod drift, plus the dharta.toml [env] declarations -
+// the report half of declare-or-bind (dev warns, build fails, diff
+// explains).
+export async function envDiffData(
+  ctx: CliContext,
+  opts: EnvOptions = {},
+): Promise<{ slug: string; drift: DriftEntry[] }> {
+  const dir = path.resolve(opts.dir ?? process.cwd());
+  await validateEnvDiffOptions(opts);
+  const slug = await inferAgentSlug(opts);
+  const local = parseDotenvFile(await readOptionalLocalFile(path.join(dir, ".env"), ".env"));
+  const declared = await declaredEnvNames(dir);
+
+  const body = await ctx.http.request<{ env: EnvEntry[] }>({
+    path: `/api/agents/${encodeURIComponent(slug)}/env`,
+  });
+  const prod = new Map(body.env.map((v) => [v.name, v]));
+
+  const drift: DriftEntry[] = [];
+  for (const [name, entry] of prod) {
+    if (!(name in local)) {
+      drift.push({ kind: "prod-only", name, secret: entry.secret });
+    } else if (!entry.secret && entry.value !== local[name]) {
+      drift.push({ kind: "value-differs", name });
+    } else if (entry.secret) {
+      drift.push({ kind: "secret", name, secret: true });
+    }
+  }
+  for (const name of Object.keys(local)) {
+    if (!prod.has(name)) drift.push({ kind: "local-only", name });
+  }
+  for (const name of declared) {
+    if (!prod.has(name) && !(name in local)) drift.push({ kind: "declared-only", name });
+  }
+  return { slug, drift };
+}
+
+export async function envDiff(ctx: CliContext, opts: EnvOptions = {}): Promise<string> {
+  const { slug, drift } = await envDiffData(ctx, opts);
+  if (drift.length === 0) return `No drift: .env and ${slug}'s prod bindings agree.`;
+  return drift.map(formatDrift).join("\n");
+}
+
+function formatDrift(d: DriftEntry): string {
+  switch (d.kind) {
+    case "prod-only":
+      return `prod only      ${d.name}${d.secret ? " (secret)" : ""} - add to .env (dharta env pull)`;
+    case "value-differs":
+      return `value differs  ${d.name} - local .env and prod disagree`;
+    case "secret":
+      return `secret         ${d.name} - prod value not comparable`;
+    case "local-only":
+      return `local only     ${d.name} - bind in prod with: dharta env set ${d.name}=...`;
+    case "declared-only":
+      return `declared only  ${d.name} - in dharta.toml [env] but bound nowhere`;
+  }
+}
+
+async function declaredEnvNames(dir: string): Promise<string[]> {
+  const raw = await readOptionalLocalFile(path.join(dir, "dharta.toml"), "dharta.toml");
+  if (!raw) return [];
+  try {
+    const parsed = TOML.parse(raw) as Record<string, unknown>;
+    const env = parsed.env;
+    return env && typeof env === "object" ? Object.keys(env) : [];
+  } catch {
+    return [];
+  }
+}
+
+export function parseDotenvFile(content: string | null): Record<string, string> {
+  const vars: Record<string, string> = {};
+  if (!content) return vars;
+  for (const raw of content.split("\n")) {
+    let line = raw.trim();
+    if (line.startsWith("export ")) line = line.slice("export ".length).trim();
+    if (!line || line.startsWith("#") || !line.includes("=")) continue;
+    const idx = line.indexOf("=");
+    const name = line.slice(0, idx).trim();
+    let value = line.slice(idx + 1).trim();
+    if (value.length >= 2 && (value[0] === '"' || value[0] === "'") && value.endsWith(value[0])) {
+      value = value.slice(1, -1);
+    } else {
+      value = value.split(" #", 1)[0].trim();
+    }
+    vars[name] = value;
+  }
+  return vars;
+}
+
+function quoteIfNeeded(value: string): string {
+  return /[\s#"']/.test(value) ? JSON.stringify(value) : value;
+}
+
+function normalizeEnvName(name: string): string {
+  return normalizeNonBlank(name, "env var name");
+}
+
+export async function validateEnvPullOptions(opts: EnvOptions = {}): Promise<void> {
+  validateAgentSelectorOptions({ agent: opts.agent, project: opts.project, dir: opts.dir });
+  const dir = path.resolve(opts.dir ?? process.cwd());
+  await validateEnvPullTarget(dir, path.join(dir, ".env"), !!opts.force);
+}
+
+export async function validateEnvDiffOptions(opts: EnvOptions = {}): Promise<void> {
+  validateAgentSelectorOptions({ agent: opts.agent, project: opts.project, dir: opts.dir });
+  await validateEnvReadDir(path.resolve(opts.dir ?? process.cwd()));
+}
+
+async function readOptionalLocalFile(file: string, label: string): Promise<string | null> {
+  try {
+    return await fs.readFile(file, "utf8");
+  } catch (error) {
+    const code = (error as NodeJS.ErrnoException).code;
+    if (code === "ENOENT") return null;
+    if (code === "EISDIR") throw new Error(`Cannot read ${label} at ${file}: expected a file, got a directory.`);
+    throw new Error(`Cannot read ${label} at ${file}: ${(error as Error).message}`);
+  }
+}
+
+async function validateEnvReadDir(dir: string): Promise<void> {
+  let stat;
+  try {
+    stat = await fs.stat(dir);
+  } catch (error) {
+    const code = (error as NodeJS.ErrnoException).code;
+    if (code === "ENOENT") throw new Error(`Cannot read env files in ${dir}: directory does not exist.`);
+    throw new Error(`Cannot read env files in ${dir}: ${(error as Error).message}`);
+  }
+  if (!stat.isDirectory()) {
+    throw new Error(`Cannot read env files in ${dir}: expected a directory.`);
+  }
+}
+
+async function validateEnvPullTarget(dir: string, target: string, force: boolean): Promise<void> {
+  let dirStat;
+  try {
+    dirStat = await fs.stat(dir);
+  } catch (error) {
+    const code = (error as NodeJS.ErrnoException).code;
+    if (code === "ENOENT") throw new Error(`Cannot write .env in ${dir}: directory does not exist.`);
+    throw new Error(`Cannot write .env in ${dir}: ${(error as Error).message}`);
+  }
+  if (!dirStat.isDirectory()) {
+    throw new Error(`Cannot write .env in ${dir}: expected a directory.`);
+  }
+
+  try {
+    const targetStat = await fs.stat(target);
+    if (targetStat.isDirectory()) {
+      throw new Error(`Cannot write .env to ${target}: expected a file, got a directory.`);
+    }
+    if (!force) {
+      throw new Error(
+        `${target} already exists. Re-run with --force to overwrite it (local-only keys are lost).`,
+      );
+    }
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return;
+    throw error;
+  }
+}
+
+async function writeEnvFile(target: string, content: string): Promise<void> {
+  try {
+    await fs.writeFile(target, content, { mode: 0o600 });
+  } catch (error) {
+    const code = (error as NodeJS.ErrnoException).code;
+    if (code === "ENOENT") throw new Error(`Cannot write .env to ${target}: parent directory does not exist.`);
+    if (code === "EISDIR") throw new Error(`Cannot write .env to ${target}: expected a file, got a directory.`);
+    throw new Error(`Cannot write .env to ${target}: ${(error as Error).message}`);
+  }
+}

package/src/commands/files.ts

@@ -0,0 +1,124 @@
+import { HttpClient } from "@dharta/sdk";
+import { randomUUID } from "node:crypto";
+import { writeFile } from "node:fs/promises";
+import type { CliContext } from "../context.js";
+import { cliFormatError, cliFormatNetworkError, cliFormatRawError } from "../api-error.js";
+import { table } from "../output.js";
+import { validateAgentSlug } from "../agent.js";
+
+// `dharta files ls|get <agent> <karta>` - the owner file-read channel (RFC 0060 D3/P3).
+//
+// Mints a short-lived `workspace_read` token OUT OF BAND from the control plane (the
+// same mint as the git-credential helper, `scope: "workspace_read"`), then GETs the
+// DATA-PLANE files routes directly with it - so file bytes flow only from the data plane,
+// never through the control plane (the BYOC residency property, D3/D8). The mint response
+// carries `files_url`, the data-plane base for this dharta.
+
+export interface WorkspaceEntry {
+  path: string;
+  kind: string;
+  size: number;
+  mode: number;
+}
+
+export interface WorkspaceListing {
+  snapshot: string;
+  entries: WorkspaceEntry[];
+}
+
+interface FilesMint {
+  token: string;
+  files_url: string;
+}
+
+async function mintFilesToken(ctx: CliContext, agent: string, instance: string): Promise<FilesMint> {
+  const res = await ctx.http.request<{ token?: string; files_url?: string }>({
+    method: "POST",
+    path: `/api/agents/${encodeURIComponent(agent)}/workspace_tokens`,
+    headers: { "Idempotency-Key": randomUUID() },
+    body: { instance, scope: "workspace_read" },
+  });
+  if (!res.token) {
+    throw new Error("The Dharta server did not return a workspace token.");
+  }
+  if (!res.files_url) {
+    throw new Error(
+      "This Dharta server does not expose the files API (files_url missing). Upgrade the server (RFC 0060).",
+    );
+  }
+  return { token: res.token, files_url: res.files_url };
+}
+
+// A data-plane HttpClient bound to the files host, authenticated with the minted token.
+// Returns the client plus the base path from `files_url` (`/workspace/<agent>/<karta>`).
+function filesClient(ctx: CliContext, mint: FilesMint): { http: HttpClient; basePath: string } {
+  const url = new URL(mint.files_url);
+  const http = new HttpClient({
+    apiKey: mint.token,
+    baseUrl: url.origin,
+    fetch: ctx.fetch,
+    formatError: cliFormatError,
+    formatNetworkError: cliFormatNetworkError,
+  });
+  return { http, basePath: url.pathname };
+}
+
+function normalizeInstance(instance: string): string {
+  const trimmed = instance.trim();
+  if (!trimmed) throw new Error("A dharta id is required.");
+  return trimmed;
+}
+
+export async function filesLsData(
+  ctx: CliContext,
+  agent: string,
+  instance: string,
+): Promise<WorkspaceListing> {
+  const slug = validateAgentSlug(agent, "agent slug");
+  const karta = normalizeInstance(instance);
+  const mint = await mintFilesToken(ctx, slug, karta);
+  const { http, basePath } = filesClient(ctx, mint);
+  const listing = await http.request<WorkspaceListing>({ path: basePath });
+  return {
+    snapshot: typeof listing.snapshot === "string" ? listing.snapshot : "",
+    entries: Array.isArray(listing.entries) ? listing.entries : [],
+  };
+}
+
+export async function filesLs(ctx: CliContext, agent: string, instance: string): Promise<string> {
+  const listing = await filesLsData(ctx, agent, instance);
+  if (listing.entries.length === 0) {
+    return `No files in ${agent}/${instance} (snapshot ${listing.snapshot || "—"}).`;
+  }
+  const rows = [...listing.entries]
+    .sort((a, b) => a.path.localeCompare(b.path))
+    .map((e) => ({ path: e.path, size: String(e.size) }));
+  return table(rows);
+}
+
+// Fetch one file's bytes. Writes to `out` (a status line is returned) or, when `out` is
+// omitted, streams the raw bytes to stdout (returns null so nothing else is printed - a
+// trailing newline would corrupt binary output).
+export async function filesGet(
+  ctx: CliContext,
+  agent: string,
+  instance: string,
+  path: string,
+  out?: string,
+): Promise<string | null> {
+  const slug = validateAgentSlug(agent, "agent slug");
+  const karta = normalizeInstance(instance);
+  const filePath = path.trim();
+  if (!filePath) throw new Error("A file path is required.");
+  const mint = await mintFilesToken(ctx, slug, karta);
+  const { http, basePath } = filesClient(ctx, mint);
+  const res = await http.raw(`${basePath}/file?path=${encodeURIComponent(filePath)}`);
+  if (!res.ok) throw await cliFormatRawError(res);
+  const bytes = Buffer.from(await res.arrayBuffer());
+  if (out) {
+    await writeFile(out, bytes);
+    return `Wrote ${bytes.length} bytes to ${out}.`;
+  }
+  process.stdout.write(bytes);
+  return null;
+}

package/src/commands/git-credential.ts

@@ -0,0 +1,78 @@
+import { HttpClient } from "@dharta/sdk";
+import { randomUUID } from "node:crypto";
+import { activeProfile, type Profile } from "../config.js";
+
+// `dharta git-credential <operation>` - a git credential helper in the protocol sense,
+// wired by `dharta login` via `credential.<git host>.helper = !dharta git-credential`.
+//
+// Two hosts, two auth models (RFC 0043 D8):
+//   - the RFC 0011 PUSH host (git_base_url): answer with the stored API key (the server
+//     ignores the username, "dharta" by convention).
+//   - the workspace CLONE host (workspace_git_base_url, the DATA PLANE): mint a per-clone
+//     read-only token OUT OF BAND (a metadata call to the control plane) and answer with
+//     it, so the clone bytes flow only from the data plane and never through the control
+//     plane. `dharta login` sets `useHttpPath=true` for this host so git passes the repo
+//     path, from which we read the karta id.
+//
+// store/erase are no-ops: the API key already lives in ~/.dharta/config.toml and the
+// minted token is short-lived (git never persists this secret).
+export async function gitCredential(
+  operation: string,
+  stdin: string,
+): Promise<string> {
+  if (operation !== "get") return "";
+
+  const profile = await activeProfile();
+
+  const attrs = new Map<string, string>();
+  for (const line of stdin.split("\n")) {
+    const idx = line.indexOf("=");
+    if (idx > 0) attrs.set(line.slice(0, idx), line.slice(idx + 1));
+  }
+
+  const protocol = attrs.get("protocol");
+  if (protocol !== "https" && protocol !== "http") return "";
+  const host = attrs.get("host");
+  if (!host) return "";
+
+  const wsBase = profile.workspace_git_base_url;
+  if (wsBase && host === new URL(wsBase).host) {
+    const token = await mintWorkspaceToken(profile, attrs.get("path") ?? "");
+    return token ? `username=karta\npassword=${token}\n` : "";
+  }
+
+  if (profile.git_base_url && host === new URL(profile.git_base_url).host) {
+    return `username=karta\npassword=${profile.api_key}\n`;
+  }
+
+  return "";
+}
+
+// Mint a read-only workspace token for the karta named by the request path. With
+// `useHttpPath=true`, git passes a path like `git/<agent>/<karta>` (no leading slash,
+// possibly with extra segments we ignore). Returns null on any failure - git then falls
+// back to its normal prompt/deny, never a crash.
+async function mintWorkspaceToken(
+  profile: Profile,
+  path: string,
+): Promise<string | null> {
+  const m = path.replace(/^\/+/, "").match(/^git\/([^/]+)\/([^/]+)/);
+  if (!m) return null;
+  const [, agent, instance] = m;
+
+  const http = new HttpClient({
+    apiKey: profile.api_key,
+    baseUrl: profile.base_url,
+  });
+  try {
+    const res = await http.request<{ token?: string }>({
+      method: "POST",
+      path: `/api/agents/${encodeURIComponent(agent)}/workspace_tokens`,
+      headers: { "Idempotency-Key": randomUUID() },
+      body: { instance },
+    });
+    return res.token ?? null;
+  } catch {
+    return null;
+  }
+}