@dharta/cli 0.6.77

package/src/setup-scan.ts

@@ -0,0 +1,154 @@
+import { spawn } from "node:child_process";
+import { existsSync, promises as fs } from "node:fs";
+import * as path from "node:path";
+import TOML from "@iarna/toml";
+import {
+  AGENT_MARKERS,
+  hasAgentMarker,
+  markerFolderRel,
+  readDeclaredHarnessType,
+  sniffHarnessType,
+  type HarnessType,
+} from "./harnesses.js";
+import type { DeployMethod } from "./manifest.js";
+
+// `dharta setup` lists every agent folder so you can pick one to configure
+// (RFC 0024 DEP-4 / D10). A folder counts if it holds ANY harness/karta
+// marker - configured or not, repo root included. Detection never
+// auto-deploys; it just surfaces candidates.
+export const MARKERS = [...AGENT_MARKERS];
+
+export interface AgentFolder {
+  dir: string; // absolute
+  rel: string; // relative to the scan root ("." = the root itself)
+  name?: string; // from dharta.toml when configured (display name)
+  slug?: string; // explicit identity from dharta.toml; when absent, derived from name
+  configured: boolean; // dharta.toml present
+  deployEnabled: boolean; // deploy = true in dharta.toml
+  deployMethod?: DeployMethod; // explicit per-agent deployment transport
+  harnessType?: HarnessType; // declared in dharta.toml or sniffed from native markers
+}
+
+// Walk up from `start` for a directory containing .git; null if none.
+export function findGitRoot(start: string): string | null {
+  let dir = path.resolve(start);
+  for (;;) {
+    if (existsSync(path.join(dir, ".git"))) return dir;
+    const parent = path.dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+
+export interface ScanOptions {
+  isGitRepo?: boolean;
+  // Test seam: returns NUL-joined `git ls-files -z` output, or null.
+  runGit?: (args: string[], cwd: string) => Promise<string | null>;
+}
+
+// Every agent folder under `root`, sorted by relative path. In a git repo we
+// union git's view of marker files - tracked AND new-but-not-ignored, at ANY
+// depth (`--cached --others --exclude-standard`) - with a shallow walk that
+// also catches directory markers like `.claude`. Outside git it is the shallow
+// walk alone (root + immediate subdirs, RFC 0024 §4). The `--others` half is
+// what surfaces a freshly `dharta create`d folder before it is committed.
+export async function scanAgentFolders(root: string, opts: ScanOptions = {}): Promise<AgentFolder[]> {
+  const absRoot = path.resolve(root);
+  const rels = new Set<string>();
+
+  if (opts.isGitRepo) {
+    const listed = await (opts.runGit ?? gitLsFiles)(
+      ["ls-files", "-z", "--cached", "--others", "--exclude-standard"],
+      absRoot,
+    );
+    for (const p of (listed ?? "").split("\0")) {
+      if (!p) continue;
+      const folder = markerFolderRel(p);
+      if (!folder) continue;
+      rels.add(folder);
+    }
+  }
+  await shallowWalk(absRoot, rels);
+
+  const folders: AgentFolder[] = [];
+  for (const rel of [...rels].sort()) {
+    folders.push(await describeFolder(path.resolve(absRoot, rel), rel));
+  }
+  return folders;
+}
+
+// Destination-agnostic setup table: folder, name, configured?, deploy enabled?,
+// and transport. Live release/version is joined separately by `dharta status`
+// when an authenticated profile is available.
+export function renderTable(folders: AgentFolder[]): string {
+  const headers = ["AGENT FOLDER", "NAME", "HARNESS", "CONFIGURED", "DEPLOY", "METHOD"];
+  const rows = folders.map((f) => [
+    f.rel === "." ? "./ (repo root)" : `./${f.rel}`,
+    f.name ?? "-",
+    f.harnessType ?? "-",
+    f.configured ? "yes" : "no",
+    f.configured ? (f.deployEnabled ? "enabled" : "disabled") : "-",
+    f.deployMethod ?? "-",
+  ]);
+  const widths = headers.map((h, i) => Math.max(h.length, ...rows.map((r) => r[i].length)));
+  const fmt = (cols: string[]) => cols.map((c, i) => c.padEnd(widths[i])).join("  ").trimEnd();
+  return [fmt(headers), ...rows.map(fmt)].join("\n");
+}
+
+async function shallowWalk(absRoot: string, rels: Set<string>): Promise<void> {
+  if (await hasMarker(absRoot)) rels.add(".");
+  let entries: import("node:fs").Dirent[];
+  try {
+    entries = await fs.readdir(absRoot, { withFileTypes: true });
+  } catch {
+    return;
+  }
+  for (const e of entries) {
+    // Skip dot-dirs (incl. .git) and node_modules as CANDIDATES - a marker
+    // like .claude makes its PARENT an agent folder, not itself.
+    if (!e.isDirectory() || e.name === "node_modules" || e.name.startsWith(".")) continue;
+    if (await hasMarker(path.join(absRoot, e.name))) rels.add(e.name);
+  }
+}
+
+async function hasMarker(dir: string): Promise<boolean> {
+  return hasAgentMarker(dir);
+}
+
+export async function describeFolder(dir: string, rel: string): Promise<AgentFolder> {
+  const folder: AgentFolder = { dir, rel: rel === "" ? "." : rel, configured: false, deployEnabled: false };
+  const tomlPath = path.join(dir, "dharta.toml");
+  if (!existsSync(tomlPath)) {
+    folder.harnessType = sniffHarnessType(dir);
+    return folder;
+  }
+
+  folder.configured = true;
+  try {
+    const raw = await fs.readFile(tomlPath, "utf8");
+    const parsed = TOML.parse(raw) as Record<string, unknown>;
+    if (typeof parsed.name === "string") folder.name = parsed.name;
+    if (typeof parsed.slug === "string") folder.slug = parsed.slug;
+    folder.deployEnabled = parsed.deploy === true;
+    if (parsed.deploy_method === "git" || parsed.deploy_method === "folder") {
+      folder.deployMethod = parsed.deploy_method;
+    }
+    folder.harnessType = readDeclaredHarnessType(raw) ?? sniffHarnessType(dir);
+  } catch {
+    // A malformed dharta.toml is still a configured folder; it stays
+    // nameless here and the manifest writer / build server reports the
+    // parse error when it matters.
+    folder.harnessType = sniffHarnessType(dir);
+  }
+  return folder;
+}
+
+function gitLsFiles(args: string[], cwd: string): Promise<string | null> {
+  return new Promise((resolve) => {
+    const proc = spawn("git", args, { cwd, stdio: ["ignore", "pipe", "ignore"] });
+    const out: Buffer[] = [];
+    proc.stdout.on("data", (c: Buffer) => out.push(c));
+    proc.on("error", () => resolve(null));
+    proc.on("close", (code) => resolve(code === 0 ? Buffer.concat(out).toString("utf8") : null));
+  });
+}

package/src/templates.ts

@@ -0,0 +1,85 @@
+// Template resolution for `dharta setup` scaffolding (RFC 0013 CLI-2 / 0024
+// DEP-4c, decision D9): fetch the current set from the control plane so CLI
+// and dashboard scaffolds never drift, with the launch set bundled in the
+// package as the offline fallback.
+
+import { promises as fs } from "node:fs";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+
+export interface Template {
+  key: string;
+  title: string;
+  description: string;
+  files: Record<string, string>;
+}
+
+export interface ResolvedTemplates {
+  templates: Template[];
+  source: "control-plane" | "bundled";
+}
+
+// How long the control-plane fetch gets before we give up and take the bundled
+// set below. `dharta create` is often a new user's first command, so it must
+// not hang on a blackholed network. Exported because anything that kills the
+// CLI on its own clock - the packed-CLI smoke test - has to allow strictly
+// longer than this: kill the process first and the fallback never runs, so the
+// only evidence left is an empty stdout+stderr.
+export const TEMPLATE_FETCH_TIMEOUT_MS = 3000;
+
+export async function resolveTemplates(
+  baseUrl: string,
+  fetchImpl?: typeof fetch,
+): Promise<ResolvedTemplates> {
+  try {
+    const f = (fetchImpl ?? globalThis.fetch).bind(globalThis);
+    const res = await f(`${baseUrl.replace(/\/+$/, "")}/agent_templates`, {
+      headers: { Accept: "application/json" },
+      signal: AbortSignal.timeout(TEMPLATE_FETCH_TIMEOUT_MS),
+    });
+    if (res.ok) {
+      const body = (await res.json()) as { templates?: Template[] };
+      if (Array.isArray(body.templates) && body.templates.length > 0) {
+        return { templates: body.templates, source: "control-plane" };
+      }
+    }
+  } catch {
+    // fall through to the bundled set
+  }
+  return { templates: await bundledTemplates(), source: "bundled" };
+}
+
+// The launch set shipped inside the package (templates/ at the package
+// root, vendored from dharta-web's lib/agent_templates — a test pins the
+// two trees identical).
+export async function bundledTemplates(): Promise<Template[]> {
+  const root = bundledTemplatesRoot();
+  const meta: Record<string, { title: string; description: string }> = {
+    blank: {
+      title: "Blank",
+      description: "A minimal skeleton. Start from an empty native instruction outline.",
+    },
+    "faq-agent": {
+      title: "FAQ agent",
+      description:
+        "A worked support-agent example: persona, knowledge section, escalation rule.",
+    },
+  };
+
+  const templates: Template[] = [];
+  for (const key of Object.keys(meta)) {
+    const dir = path.join(root, key);
+    const files: Record<string, string> = {};
+    for (const name of await fs.readdir(dir)) {
+      files[name] = await fs.readFile(path.join(dir, name), "utf8");
+    }
+    templates.push({ key, ...meta[key], files });
+  }
+  return templates;
+}
+
+export function bundledTemplatesRoot(): string {
+  // src/templates.ts compiles to dist/templates.js; templates/ sits at
+  // the package root either way.
+  return path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "templates");
+}

package/src/validators.ts

@@ -0,0 +1,124 @@
+export function validateDateOnly(value: string, flag: string): void {
+  normalizeDateOnly(value, flag);
+}
+
+export function normalizeDateOnly(value: string, flag: string): string {
+  const normalized = value.trim();
+  if (!isDateOnly(normalized)) {
+    throw new Error(`${flag} must use YYYY-MM-DD, e.g. 2026-05-18.`);
+  }
+  return normalized;
+}
+
+export function validateIsoTimestamp(value: string, flag: string): void {
+  normalizeIsoTimestamp(value, flag);
+}
+
+export function normalizeIsoTimestamp(value: string, flag: string): string {
+  const normalized = value.trim();
+  const match = normalized.match(/^(\d{4}-\d{2}-\d{2})T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:\d{2})$/);
+  if (!match) {
+    throw isoTimestampError(flag);
+  }
+  if (!isDateOnly(match[1]!)) throw isoTimestampError(flag);
+
+  const date = new Date(normalized);
+  if (Number.isNaN(date.getTime())) throw isoTimestampError(flag);
+  return normalized;
+}
+
+export function parseReleaseVersion(value: string, flag: string): number {
+  const normalized = value.trim();
+  if (!normalized) throw new Error(`${flag} cannot be blank.`);
+  const stripped = normalized.startsWith("v") ? normalized.slice(1) : normalized;
+  if (!/^[1-9]\d*$/.test(stripped)) {
+    throw new Error(`${flag} must be a release version like v3 or 3.`);
+  }
+  const parsed = Number(stripped);
+  if (!Number.isSafeInteger(parsed)) {
+    throw new Error(`${flag} must be a release version like v3 or 3.`);
+  }
+  return parsed;
+}
+
+export function parsePositiveInteger(value: string, label: string): number {
+  const normalized = value.trim();
+  if (!/^[1-9]\d*$/.test(normalized)) {
+    throw new Error(`${label} must be a positive whole number.`);
+  }
+  const parsed = Number(normalized);
+  if (!Number.isSafeInteger(parsed)) {
+    throw new Error(`${label} must be a positive whole number.`);
+  }
+  return parsed;
+}
+
+export function normalizeNonBlank(value: string, label: string): string {
+  const normalized = value.trim();
+  if (!normalized) throw new Error(`${label} cannot be blank.`);
+  return normalized;
+}
+
+export function normalizeHttpUrl(value: string, flag: string): string {
+  const normalized = normalizeNonBlank(value, flag);
+  let parsed: URL;
+  try {
+    parsed = new URL(normalized);
+  } catch {
+    throw new Error(`${flag} must be an absolute http(s) URL.`);
+  }
+  if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+    throw new Error(`${flag} must be an absolute http(s) URL.`);
+  }
+  return normalized;
+}
+
+export function normalizeTimezone(value: string, flag: string): string {
+  const normalized = normalizeNonBlank(value, flag);
+  try {
+    Intl.DateTimeFormat("en-US", { timeZone: normalized }).format(new Date());
+  } catch {
+    throw new Error(`${flag} must be a valid IANA timezone, e.g. UTC or America/Los_Angeles.`);
+  }
+  return normalized;
+}
+
+export function closestChoice(value: string, allowed: readonly string[]): string | null {
+  if (value.length === 0) return null;
+  let best: { choice: string; distance: number } | null = null;
+  for (const choice of allowed) {
+    const distance = levenshtein(value, choice);
+    if (distance <= 2 && (!best || distance < best.distance)) {
+      best = { choice, distance };
+    }
+  }
+  return best?.choice ?? null;
+}
+
+function isDateOnly(value: string): boolean {
+  if (!/^\d{4}-\d{2}-\d{2}$/.test(value)) return false;
+  const date = new Date(`${value}T00:00:00.000Z`);
+  return !Number.isNaN(date.getTime()) && date.toISOString().slice(0, 10) === value;
+}
+
+function isoTimestampError(flag: string): Error {
+  return new Error(`${flag} must be an ISO timestamp, e.g. 2026-05-18T00:00:00Z.`);
+}
+
+function levenshtein(a: string, b: string): number {
+  const prev = Array.from({ length: b.length + 1 }, (_, i) => i);
+  const curr = Array<number>(b.length + 1);
+  for (let i = 1; i <= a.length; i += 1) {
+    curr[0] = i;
+    for (let j = 1; j <= b.length; j += 1) {
+      const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+      curr[j] = Math.min(
+        curr[j - 1]! + 1,
+        prev[j]! + 1,
+        prev[j - 1]! + cost,
+      );
+    }
+    prev.splice(0, prev.length, ...curr);
+  }
+  return prev[b.length]!;
+}

package/src/version-check.ts

@@ -0,0 +1,75 @@
+import { promises as fs } from "node:fs";
+import * as path from "node:path";
+
+export const NPM_LATEST_URL = "https://registry.npmjs.org/@dharta.ai%2fcli/latest";
+
+export interface VersionCheckOptions {
+  root: string;
+  currentVersion?: string;
+  fetchImpl?: typeof fetch;
+  latestUrl?: string;
+}
+
+export type VersionCheck =
+  | { status: "current"; current: string; latest: string }
+  | { status: "ahead"; current: string; latest: string }
+  | { status: "outdated"; current: string; latest: string }
+  | { status: "unknown"; reason: string; current?: string };
+
+export async function checkNpmLatestVersion(opts: VersionCheckOptions): Promise<VersionCheck> {
+  const current = opts.currentVersion ?? (await readPackageVersion(opts.root));
+  if (!current) return { status: "unknown", reason: "could not read package.json" };
+
+  const latest = await fetchLatestVersion(opts);
+  if (!latest) return { status: "unknown", reason: "npm registry did not return a version", current };
+
+  const comparison = compareVersions(current, latest);
+  if (comparison === null) return { status: "unknown", reason: `could not compare ${current} with ${latest}`, current };
+  if (comparison === 0) return { status: "current", current, latest };
+  if (comparison > 0) return { status: "ahead", current, latest };
+  return { status: "outdated", current, latest };
+}
+
+async function readPackageVersion(root: string): Promise<string | null> {
+  try {
+    const raw = await fs.readFile(path.join(root, "package.json"), "utf8");
+    const parsed = JSON.parse(raw) as { version?: unknown };
+    return typeof parsed.version === "string" ? parsed.version : null;
+  } catch {
+    return null;
+  }
+}
+
+async function fetchLatestVersion(opts: VersionCheckOptions): Promise<string | null> {
+  const fetchImpl = opts.fetchImpl ?? globalThis.fetch;
+  const url = opts.latestUrl ?? NPM_LATEST_URL;
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), 1500);
+  try {
+    const res = await fetchImpl(url, { signal: controller.signal });
+    if (!res.ok) return null;
+    const body = (await res.json()) as { version?: unknown };
+    return typeof body.version === "string" ? body.version : null;
+  } catch {
+    return null;
+  } finally {
+    clearTimeout(timeout);
+  }
+}
+
+function compareVersions(a: string, b: string): -1 | 0 | 1 | null {
+  const left = parseVersion(a);
+  const right = parseVersion(b);
+  if (!left || !right) return null;
+  for (let i = 0; i < 3; i++) {
+    if (left[i] < right[i]) return -1;
+    if (left[i] > right[i]) return 1;
+  }
+  return 0;
+}
+
+function parseVersion(version: string): [number, number, number] | null {
+  const match = version.match(/^(\d+)\.(\d+)\.(\d+)(?:[-+].*)?$/);
+  if (!match) return null;
+  return [Number(match[1]), Number(match[2]), Number(match[3])];
+}

package/templates/blank/CLAUDE.md

@@ -0,0 +1,21 @@
+# My agent
+
+Describe who your agent is and how it should behave. This file is the
+agent's instructions - it reads them at the start of every conversation.
+
+## Personality
+
+- Friendly and concise.
+
+## What you can help with
+
+- Replace this list with the things your agent should handle.
+
+## Knowledge
+
+Paste the facts your agent should know here: product details, policies,
+FAQ answers. The agent sees this whole file every conversation.
+
+## Rules
+
+- If you don't know the answer, say so honestly. Never make things up.

package/templates/blank/dharta.toml

@@ -0,0 +1,11 @@
+# Dharta deploy manifest. This source template is Claude-shaped; create flows
+# keep CLAUDE.md for Claude Code or translate it to the selected harness's
+# native instruction file. No build step or entry module is needed.
+[harness]
+type = "claude-code"
+
+# Declare the environment variables your agent depends on; bind them with
+# .env locally and `dharta env set` in production (declare-or-bind).
+[env]
+# Example:
+#   MY_API_URL = { required = true, description = "Backend base URL" }

package/templates/faq-agent/CLAUDE.md

@@ -0,0 +1,51 @@
+# Sage - the Acme Outfitters support assistant
+
+You are **Sage**, the friendly support assistant for **Acme Outfitters**,
+an online outdoor-gear shop.
+
+> Replace the name, company, and the Knowledge section below with your
+> own. Everything in this file is the agent's instructions - it reads the
+> whole file at the start of every conversation.
+
+## Personality
+
+- Warm, clear, and brief. Sound like a helpful human, not a script.
+- Greet a brand-new conversation with one short, welcoming line.
+- Keep replies to 1-3 sentences unless the customer asks for detail.
+
+## Knowledge
+
+Answer questions using only the facts below. If the answer isn't here,
+say so honestly instead of guessing.
+
+### Shipping
+
+- Standard shipping takes 3-5 business days and costs $5.
+- Orders over $50 ship free.
+- We currently ship within the United States only.
+
+### Returns & exchanges
+
+- Unused items can be returned within 30 days for a full refund.
+- Exchanges are free - we email a prepaid return label.
+- Sale items are final sale.
+
+### Products
+
+- *TrailLite* day pack: 22L, water-resistant, fits a 15" laptop.
+- *Basecamp* tent: 2-person, three-season, sets up in under 5 minutes.
+- *Ember* insulated bottle: keeps drinks hot 12 hours, cold 24 hours.
+
+### Account & orders
+
+- Order confirmations and tracking links are emailed automatically.
+- Customers can check order status from the link in their confirmation
+  email.
+
+## Escalation
+
+If the customer asks about something not covered here - a specific
+order's status, a billing problem, or anything that needs a human - say
+you'll connect them with the team and ask them to email
+**support@example.com**. Never invent order details or make promises on
+the team's behalf.

package/templates/faq-agent/dharta.toml

@@ -0,0 +1,11 @@
+# Dharta deploy manifest. This source template is Claude-shaped; create flows
+# keep CLAUDE.md for Claude Code or translate it to the selected harness's
+# native instruction file. No build step or entry module is needed.
+[harness]
+type = "claude-code"
+
+# Declare the environment variables your agent depends on; bind them with
+# .env locally and `dharta env set` in production (declare-or-bind).
+[env]
+# Example:
+#   MY_API_URL = { required = true, description = "Backend base URL" }