@dharta/cli 0.6.77 → 0.6.78

package/dist/exit-codes.js

@@ -0,0 +1,107 @@
+// Exit-code taxonomy (RFC 0048 D1/P5). A script that pipes `dharta` needs to
+// branch on *why* a command failed without parsing English, so every failure
+// maps to one of these codes. The numbers are a public contract: change a
+// meaning and every caller's `if [ $? -eq 4 ]` silently means something else.
+//
+// `dharta doctor` is the one exception: it reports an unhealthy local setup
+// with its own exit 1 without throwing, so it never reaches this map.
+import { INVALID_IDEMPOTENCY_KEY_CODE } from "@dharta/sdk";
+export const EXIT_SUCCESS = 0;
+export const EXIT_GENERAL = 1;
+export const EXIT_USAGE = 2;
+export const EXIT_NOT_AUTHENTICATED = 3;
+export const EXIT_FORBIDDEN = 4;
+export const EXIT_NOT_FOUND = 5;
+export const EXIT_VALIDATION = 6;
+export const EXIT_NETWORK = 7;
+// A wrong invocation: an unknown flag, a bad choice, a missing argument, a
+// profile that is not in the config file. Commander raises its own version of
+// this; throw CliUsageError for the ones the CLI detects itself.
+//
+// The line, applied across every curated command (RFC 0048 P9): a throw that
+// rejects a value the caller TYPED is a usage error. A throw that reports the
+// state of the world - a file that is not there, a server too old to answer, a
+// build that failed - is a plain Error and exits 1. `test/usage-exit-code.test.ts`
+// holds both halves: a table exercising each validator, and a source scan that
+// makes a new plain Error in a command module argue for itself.
+export class CliUsageError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "CliUsageError";
+    }
+}
+// The control plane answered with a non-2xx status.
+export class CliApiError extends Error {
+    status;
+    body;
+    constructor(message, status, body) {
+        super(message);
+        this.name = "CliApiError";
+        this.status = status;
+        this.body = body;
+    }
+}
+// The control plane could not be reached at all (DNS, refused connection, TLS).
+// Distinct from CliApiError: retrying may help, and no request was authorized.
+export class CliNetworkError extends Error {
+    url;
+    constructor(message, url) {
+        super(message);
+        this.name = "CliNetworkError";
+        this.url = url;
+    }
+}
+export function isCommanderError(err) {
+    const code = err?.code;
+    return typeof code === "string" && code.startsWith("commander.");
+}
+export function exitCodeForError(err) {
+    if (isCommanderError(err)) {
+        const exitCode = err.exitCode;
+        return exitCode === 0 ? EXIT_SUCCESS : EXIT_USAGE;
+    }
+    if (err instanceof CliUsageError)
+        return EXIT_USAGE;
+    // The SDK rejects a malformed Idempotency-Key wherever it was supplied,
+    // including a header a caller wrote by hand with `dharta api -H`, which never
+    // passes through a CLI validator. It is still a value the caller typed, so it
+    // gets the code every other rejected value gets. Matched on the stable `code`
+    // rather than the class, so a duplicated SDK install cannot break it.
+    if (isInvalidIdempotencyKeyError(err))
+        return EXIT_USAGE;
+    if (err instanceof CliNetworkError)
+        return EXIT_NETWORK;
+    const status = err?.status;
+    if (typeof status === "number")
+        return exitCodeForStatus(status);
+    if (isNotAuthenticatedError(err))
+        return EXIT_NOT_AUTHENTICATED;
+    return EXIT_GENERAL;
+}
+// `Not logged in.` is raised locally when no credential is stored, before any
+// request goes out. It is the same condition a 401 reports, so it gets the same
+// exit code - otherwise `dharta whoami` means one thing logged out and another
+// with a revoked key. Commands that fall back when unauthenticated test the
+// same predicate, so the two readings cannot drift apart.
+export function isInvalidIdempotencyKeyError(err) {
+    return err?.code === INVALID_IDEMPOTENCY_KEY_CODE;
+}
+export function isNotAuthenticatedError(err) {
+    return err instanceof Error && /^Not logged in\b/.test(err.message);
+}
+export function exitCodeForStatus(status) {
+    switch (status) {
+        case 401:
+            return EXIT_NOT_AUTHENTICATED;
+        case 403:
+            return EXIT_FORBIDDEN;
+        case 404:
+            return EXIT_NOT_FOUND;
+        case 409:
+        case 422:
+            return EXIT_VALIDATION;
+        default:
+            return EXIT_GENERAL;
+    }
+}
+//# sourceMappingURL=exit-codes.js.map

package/dist/exit-codes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"exit-codes.js","sourceRoot":"","sources":["../src/exit-codes.ts"],"names":[],"mappings":"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"}

package/dist/genui.d.ts

@@ -0,0 +1,178 @@
+export declare const BUNDLE_FORMAT = "dharta.genui-bundle.v1";
+export declare const MAX_BUNDLE_BYTES: number;
+export declare const MAX_COMPONENTS = 128;
+export declare const MAX_WORKER_BYTES: number;
+export declare const MAX_HTML_BYTES: number;
+export declare const MAX_EVENTS = 64;
+export declare const MAX_EVENT_NAME_LENGTH = 128;
+export declare const EVENT_CADENCES: readonly ["agent_action", "reference", "side_effect"];
+export declare const TIER1_BUILTINS: readonly ["Badge", "Button", "Card", "Checkbox", "Column", "Divider", "Heading", "Row", "Select", "Text", "TextField"];
+export declare const IDENTIFIER: RegExp;
+export declare const DEFAULT_SOURCE_DIR = "genui/components";
+export declare const COMPONENT_SPEC_FILE = "component.json";
+export declare const TIER2_SOURCE_FILE = "worker.js";
+export declare const TIER3_SOURCE_FILE = "index.html";
+/** A `[genui]` section, or a bundle, that the data plane would reject. */
+export declare class GenuiError extends Error {
+}
+export interface GenuiComponent {
+    name: string;
+    tier: 1 | 2 | 3;
+}
+export interface GenuiSection {
+    catalogId: string;
+    version: number;
+    /** Release-relative path to the built bundle; null when Tier-1 only. */
+    bundle: string | null;
+    bundleSha256: string | null;
+    components: GenuiComponent[];
+    enabled: boolean;
+    /** Release-relative component source folder, from `[genui.build] source`. */
+    source: string;
+}
+export interface ParseGenuiOptions {
+    /**
+     * The data plane requires bundle_sha256 whenever bundle is set, and so does
+     * every read path here. `dharta genui build` is the one exception: it is the
+     * thing that produces the digest, so it must be able to parse a manifest that
+     * declares a bundle it has not built yet.
+     */
+    requireDigest?: boolean;
+    /**
+     * The manifest's raw text. Supplied so `version` can be judged by its TOML
+     * literal rather than by the JavaScript number it parsed to - see
+     * `rejectFloatVersion`.
+     */
+    text?: string;
+}
+/**
+ * Parse the `[genui]` table out of a loaded `dharta.toml`. Returns null when
+ * there is no section (generative UI is opt-in); throws `GenuiError` on a
+ * section the data plane would reject.
+ */
+export declare function parseGenuiSection(manifest: Record<string, unknown>, options?: ParseGenuiOptions): GenuiSection | null;
+/**
+ * The catalog the data plane synthesizes when `[genui]` declares no bundle
+ * (bundle.py load_genui_bundle_with_bytes). It runs the SAME payload validation
+ * over it, so a Tier-1-only catalog is not unvalidated: a component whose name
+ * is not a Dharta builtin, or a 129th component, is rejected at deploy.
+ */
+export declare function synthesizeBundlePayload(section: GenuiSection): Record<string, unknown>;
+/**
+ * Throw `GenuiError` unless `payload` is a bundle this manifest can ship.
+ *
+ * `rawText` is the bundle file's bytes as read off disk, when there was one.
+ * The whole integer rule lives here because JavaScript cannot see it in the
+ * parsed value: `JSON.parse` collapses `1.0` to `1`, while Python's
+ * `json.loads` yields a float that fails `isinstance(..., int)`.
+ */
+export declare function validateBundlePayload(payload: unknown, section: GenuiSection, rawText?: string): void;
+/**
+ * Byte-for-byte reproducible JSON, matching the data plane's own canonical form
+ * (`json.dumps(..., ensure_ascii=True, separators=(",", ":"), sort_keys=True)`):
+ * sorted keys, compact separators, ASCII only. The digest recorded in
+ * dharta.toml is over these exact bytes, so a rebuild of unchanged sources must
+ * produce an unchanged file.
+ *
+ * Written out key by key rather than sorted into an object and handed to
+ * `JSON.stringify`, because a JavaScript object does not preserve the order you
+ * insert integer-like keys in: it emits those first, in ascending numeric
+ * order. `{"1","10","2","alpha"}` is Python's order and `{"1","2","10","alpha"}`
+ * is what an object round-trip produces, which is a different digest for the
+ * same catalog.
+ *
+ * Numbers are JavaScript doubles, and this writes back whatever `JSON.parse`
+ * produced. `1.0` therefore serializes as `1` and `-0.0` as `0` - the source
+ * spelling is already gone by the time the value gets here, and re-deriving it
+ * is not possible. Both forms are the same double on the data plane too, so
+ * this only ever narrows the spelling, never the value.
+ *
+ * Two shapes a double cannot carry at all: an integer beyond
+ * `Number.MAX_SAFE_INTEGER`, which arrives already rounded, and a float that
+ * overflows a double, which arrives as `Infinity` and would be written out as
+ * `null`. `findUnsafeNumberLiteral` refuses both in a component.json rather
+ * than letting the build ship a number the source never wrote.
+ */
+export declare function canonicalJson(value: unknown): string;
+export declare function sha256Hex(bytes: Buffer | string): string;
+/** A `dharta.toml` read once and reused by every genui code path. */
+export interface ManifestSource {
+    path: string;
+    text: string;
+    parsed: Record<string, unknown>;
+}
+export interface LoadedGenui extends ManifestSource {
+    section: GenuiSection | null;
+}
+/** Read `dir/dharta.toml`. Throws when it is missing or unparseable. */
+export declare function readManifest(dir: string): Promise<ManifestSource>;
+/**
+ * Read and parse an agent's `[genui]` section once. Every command path threads
+ * the result rather than re-reading the manifest: `dharta dev`'s doctor already
+ * holds a parsed one and hands it straight in.
+ */
+export declare function loadGenui(source: string | ManifestSource, options?: ParseGenuiOptions): Promise<LoadedGenui>;
+export interface GenuiCheck {
+    manifest: string;
+    /** Null when there is no [genui] section, or when it failed to parse. */
+    section: GenuiSection | null;
+    /** Every reason the data plane would reject this release. Empty = accepted. */
+    problems: string[];
+}
+/**
+ * Report every reason the data plane would reject this agent's `[genui]`
+ * declaration. Shared by `dharta genui check`, `dharta dev`'s doctor
+ * (warnings), and the deploy pre-flight (refusal) so all three say the same
+ * thing. Pass an already-read manifest to avoid a second read.
+ */
+export declare function checkGenui(source: string | ManifestSource): Promise<GenuiCheck>;
+export interface GenuiPreflightOptions {
+    /**
+     * The files this deploy will actually ship, release-relative. Deploy sends a
+     * Git-filtered tree (committed HEAD, or a gitignore-honoring tarball) while
+     * every check here reads the WORKING tree, so an ignored bundle passes
+     * locally and arrives missing. Asking the deploy's own file list - rather
+     * than re-deriving the answer from ignore rules - gets force-added files and
+     * non-ASCII names right for free. Optional: without it the pre-flight simply
+     * skips that question.
+     */
+    deployFiles?: () => Promise<string[]>;
+}
+/**
+ * Deploy pre-flight: refuse locally, before anything is pushed or uploaded,
+ * with the message the release validator would return.
+ */
+export declare function genuiPreflight(dir: string, options?: GenuiPreflightOptions): Promise<void>;
+export interface GenuiStatus {
+    manifest: string;
+    /** False when there is no [genui] section: generative UI is off for this agent. */
+    configured: boolean;
+    catalogId?: string;
+    version?: number;
+    enabled?: boolean;
+    bundle?: string | null;
+    bundleSha256?: string | null;
+    components: GenuiComponent[];
+}
+/** `dharta genui check`: the structured result. Throws when something is wrong. */
+export declare function genuiCheckData(dir: string): Promise<GenuiStatus>;
+export declare function formatGenuiStatus(status: GenuiStatus): string;
+export interface BuildResult {
+    status: "built" | "nothing-to-build";
+    /** Release-relative bundle path, when one was written. */
+    bundle?: string;
+    digest?: string;
+    components: number;
+}
+/**
+ * Compile `[genui.build] source` into a validated bundle payload. Nothing is
+ * written: this is the seam at the data plane's contract, so a caller can
+ * assert on the exact object a release would carry.
+ */
+export declare function compileBundlePayload(section: GenuiSection, dir: string): Promise<Record<string, unknown>>;
+/**
+ * Compile `[genui.build] source` into the bundle at `[genui] bundle` and record
+ * its digest in dharta.toml. Validates everything the data plane validates
+ * before writing, so a bad catalog fails here rather than at deploy.
+ */
+export declare function buildGenui(dir: string, log: (line: string) => void): Promise<BuildResult>;