@dharta/cli 0.6.77 → 0.6.78

package/node_modules/@dharta/contracts/src/artifact-runtime.ts

@@ -0,0 +1,520 @@
+import type {
+  ArtifactDeclaration,
+  ArtifactDeclarationV1,
+  ArtifactDeclarationV2,
+  ArtifactExecutionRenewalWire,
+  ArtifactExecutionSessionWire,
+  ArtifactManifestDocumentV2,
+  ArtifactSummaryV1,
+  ArtifactSummaryV2,
+} from "./artifact-runtime.generated.js";
+import { ARTIFACT_RUNTIME_CATALOG } from "./artifact-runtime.generated.js";
+import { isRfc3339DateTime, RFC3339_DATE_TIME } from "./artifact-runtime-formats.js";
+import {
+  validateArtifactV1 as generatedValidateV1,
+  validateArtifactV2 as generatedValidateV2,
+  validateArtifactManifestDocument as generatedValidateManifest,
+  validateArtifactSummaryV1 as generatedValidateSummaryV1,
+  validateArtifactSummaryV2 as generatedValidateSummaryV2,
+  validateArtifactExecutionSession as generatedValidateExecutionSession,
+  validateArtifactExecutionRenewal as generatedValidateExecutionRenewal,
+} from "./artifact-runtime-validators.generated.js";
+
+export * from "./artifact-runtime.generated.js";
+
+const catalog = ARTIFACT_RUNTIME_CATALOG;
+
+export const ARTIFACT_CONTRACT_VERSION = catalog.contract_version;
+export const ARTIFACT_MANIFEST_BOUNDS = catalog.manifest;
+export const ARTIFACT_TREE_BOUNDS = catalog.trees;
+export const ARTIFACT_RUNTIME_CONTRACT = catalog.runtime;
+export const ARTIFACT_PORTABLE_SHARING_CONTRACT = catalog.portable_sharing;
+export const ARTIFACT_ACCESS_CONTRACT = catalog.access;
+export const ARTIFACT_HTTP_CONTRACT = catalog.http;
+
+function openApiValue(value: unknown): unknown {
+  if (Array.isArray(value)) return value.map(openApiValue);
+  if (typeof value !== "object" || value === null) return value;
+  return Object.fromEntries(
+    Object.entries(value).map(([key, item]) => [
+      key,
+      key === "$ref" && typeof item === "string"
+        ? item.replace("#/$defs/", "#/components/schemas/")
+        : openApiValue(item),
+    ]),
+  );
+}
+
+export const ARTIFACT_OPENAPI_SCHEMAS = openApiValue(catalog.schemas) as Record<
+  string,
+  unknown
+>;
+
+export class ArtifactContractError extends Error {
+  constructor(readonly code: string) {
+    super(code);
+    this.name = "ArtifactContractError";
+  }
+}
+
+/**
+ * The subset of Ajv's ErrorObject that the x-dharta-error mapping reads. The
+ * validators are Ajv-standalone output compiled at codegen time (see
+ * generate-artifact-runtime-bindings.mjs), so these are the exact error
+ * objects Ajv produces — typed locally so Ajv itself stays a devDependency.
+ */
+interface WireValidationError {
+  keyword: string;
+  schemaPath: string;
+  params: Record<string, unknown>;
+}
+
+interface WireValidateFunction {
+  (value: unknown): boolean;
+  errors?: WireValidationError[] | null;
+}
+
+const validateV1 = generatedValidateV1 as WireValidateFunction;
+const validateV2 = generatedValidateV2 as WireValidateFunction;
+const validateManifest = generatedValidateManifest as WireValidateFunction;
+const validateSummaryV1 = generatedValidateSummaryV1 as WireValidateFunction;
+const validateSummaryV2 = generatedValidateSummaryV2 as WireValidateFunction;
+const validateExecutionSession =
+  generatedValidateExecutionSession as WireValidateFunction;
+const validateExecutionRenewal =
+  generatedValidateExecutionRenewal as WireValidateFunction;
+
+const schemaBundle = { $defs: catalog.schemas };
+const v1ErrorSchema = { ...catalog.schemas.artifact_v1, ...schemaBundle };
+const v2ErrorSchema = { ...catalog.schemas.artifact_v2, ...schemaBundle };
+const manifestErrorSchema = { ...catalog.schemas.manifest_document, ...schemaBundle };
+
+interface Rfc3339Instant {
+  epochSecond: number;
+  fraction: string;
+}
+
+function rfc3339Instant(value: string): Rfc3339Instant | null {
+  const fields = RFC3339_DATE_TIME.exec(value);
+  if (!fields || !isRfc3339DateTime(value)) return null;
+  const year = Number(fields[1]);
+  const month = Number(fields[2]);
+  const day = Number(fields[3]);
+  const hour = Number(fields[4]);
+  const minute = Number(fields[5]);
+  const second = Number(fields[6]);
+  const instant = new Date(0);
+  instant.setUTCFullYear(year, month - 1, day);
+  instant.setUTCHours(hour, minute, second, 0);
+  const offsetMinutes = fields[8] === "Z"
+    ? 0
+    : (fields[9] === "-" ? -1 : 1) * (Number(fields[10]) * 60 + Number(fields[11]));
+  return {
+    epochSecond: (instant.getTime() - offsetMinutes * 60_000) / 1_000,
+    fraction: fields[7] ?? "",
+  };
+}
+
+function compareInstants(left: Rfc3339Instant, right: Rfc3339Instant): number {
+  if (left.epochSecond !== right.epochSecond) {
+    return left.epochSecond < right.epochSecond ? -1 : 1;
+  }
+  const width = Math.max(left.fraction.length, right.fraction.length);
+  const leftFraction = left.fraction.padEnd(width, "0");
+  const rightFraction = right.fraction.padEnd(width, "0");
+  return leftFraction < rightFraction ? -1 : leftFraction > rightFraction ? 1 : 0;
+}
+
+export type ArtifactSummaryWire = ArtifactSummaryV1 | ArtifactSummaryV2;
+
+const accessPatterns = {
+  publicToken: new RegExp(ARTIFACT_ACCESS_CONTRACT.public_token_pattern),
+  executionId: new RegExp(ARTIFACT_ACCESS_CONTRACT.execution_id_pattern),
+  artifactVersionId: new RegExp(ARTIFACT_ACCESS_CONTRACT.artifact_version_id_pattern),
+  handoffToken: new RegExp(ARTIFACT_ACCESS_CONTRACT.handoff_token_pattern),
+  originLabel: new RegExp(ARTIFACT_ACCESS_CONTRACT.origin_label_pattern),
+} as const;
+
+export function isArtifactPublicToken(value: unknown): value is string {
+  return typeof value === "string" && accessPatterns.publicToken.test(value);
+}
+
+export function isArtifactExecutionId(value: unknown): value is string {
+  return typeof value === "string" && accessPatterns.executionId.test(value);
+}
+
+export function isArtifactVersionId(value: unknown): value is string {
+  return typeof value === "string" && accessPatterns.artifactVersionId.test(value);
+}
+
+export function isArtifactHandoffToken(value: unknown): value is string {
+  return typeof value === "string" && accessPatterns.handoffToken.test(value);
+}
+
+export function isArtifactOriginLabel(value: unknown): value is string {
+  return typeof value === "string" && accessPatterns.originLabel.test(value);
+}
+
+function schemaNode(schema: unknown, schemaPath: string): unknown {
+  // schemaPath is a JSON Schema URI fragment: absolute (base URI + "#/...")
+  // when the failing keyword lives in the $id-anchored standalone bundle,
+  // relative ("#/...") from nested subschema validators. Only the fragment
+  // addresses into the error schema, which carries the target subschema at
+  // its root plus the shared $defs, so both forms resolve.
+  const hash = schemaPath.indexOf("#");
+  const fragment = hash === -1 ? schemaPath : schemaPath.slice(hash + 1);
+  const parts = fragment
+    .replace(/^\/?/, "")
+    .split("/")
+    .filter(Boolean)
+    .map((part) => part.replaceAll("~1", "/").replaceAll("~0", "~"));
+  let node: unknown = schema;
+  for (const part of parts) {
+    if (typeof node !== "object" || node === null || !(part in node)) break;
+    node = (node as Record<string, unknown>)[part];
+  }
+  return node;
+}
+
+function declaredError(schema: unknown, error: WireValidationError): string {
+  if (error.keyword === "required") {
+    const parentPath = error.schemaPath.replace(/\/required$/, "");
+    const parent = schemaNode(schema, parentPath);
+    const missing = error.params.missingProperty;
+    if (typeof parent === "object" && parent !== null && typeof missing === "string") {
+      const properties = (parent as Record<string, unknown>).properties;
+      if (typeof properties === "object" && properties !== null) {
+        const property = (properties as Record<string, unknown>)[missing];
+        if (typeof property === "object" && property !== null) {
+          const code = (property as Record<string, unknown>)["x-dharta-error"];
+          if (typeof code === "string") return code;
+        }
+      }
+    }
+  }
+
+  let path = error.schemaPath;
+  while (path) {
+    const node = schemaNode(schema, path);
+    if (typeof node === "object" && node !== null) {
+      const code = (node as Record<string, unknown>)["x-dharta-error"];
+      if (typeof code === "string") return code;
+    }
+    const parent = path.replace(/\/[^/]+$/, "");
+    if (parent === path) break;
+    path = parent;
+  }
+  return "artifact_contract_invalid";
+}
+
+function validateArtifact(
+  value: unknown,
+): { validator: WireValidateFunction; schema: unknown } {
+  if (typeof value !== "object" || value === null) {
+    throw new ArtifactContractError("artifact_contract_invalid");
+  }
+  const version = (value as Record<string, unknown>).contract_version;
+  const selected = version === 1
+    ? { validator: validateV1, schema: v1ErrorSchema }
+    : { validator: validateV2, schema: v2ErrorSchema };
+  if (!selected.validator(value)) {
+    const first = selected.validator.errors?.[0];
+    throw new ArtifactContractError(
+      first ? declaredError(selected.schema, first) : "artifact_contract_invalid",
+    );
+  }
+  if (version === 2) validateV2ByteAndDepthBounds(value as Record<string, unknown>);
+  return selected;
+}
+
+function utf8Bytes(value: string): number {
+  let bytes = 0;
+  for (const character of value) {
+    const point = character.codePointAt(0) ?? 0;
+    bytes += point <= 0x7f ? 1 : point <= 0x7ff ? 2 : point <= 0xffff ? 3 : 4;
+  }
+  return bytes;
+}
+
+function hasUnpairedSurrogate(value: string): boolean {
+  for (let index = 0; index < value.length; index += 1) {
+    const unit = value.charCodeAt(index);
+    if (unit >= 0xd800 && unit <= 0xdbff) {
+      const next = value.charCodeAt(index + 1);
+      if (!(next >= 0xdc00 && next <= 0xdfff)) return true;
+      index += 1;
+    } else if (unit >= 0xdc00 && unit <= 0xdfff) {
+      return true;
+    }
+  }
+  return false;
+}
+
+function validateV2ByteAndDepthBounds(value: Record<string, unknown>): void {
+  const root = value.root as string;
+  const title = value.title as string;
+  if (hasUnpairedSurrogate(title)) {
+    throw new ArtifactContractError("artifact_title_invalid");
+  }
+  if (
+    hasUnpairedSurrogate(root)
+    ||
+    utf8Bytes(root) > ARTIFACT_MANIFEST_BOUNDS.max_root_bytes
+    || root.split("/").length > ARTIFACT_MANIFEST_BOUNDS.max_root_depth
+  ) {
+    throw new ArtifactContractError("artifact_root_invalid");
+  }
+  const entry = value.entry;
+  if (typeof entry === "string") {
+    if (
+      hasUnpairedSurrogate(entry)
+      || utf8Bytes(entry) > ARTIFACT_MANIFEST_BOUNDS.max_entry_bytes
+      || entry.split("/").length > ARTIFACT_MANIFEST_BOUNDS.max_entry_depth
+    ) {
+      throw new ArtifactContractError("artifact_entry_invalid");
+    }
+  }
+  const run = value.run;
+  if (typeof run === "string") {
+    if (
+      hasUnpairedSurrogate(run)
+      || utf8Bytes(run) > ARTIFACT_MANIFEST_BOUNDS.max_run_bytes
+    ) {
+      throw new ArtifactContractError("artifact_run_invalid");
+    }
+  }
+  const inputs = value.inputs as Record<string, { source: string }>;
+  for (const input of Object.values(inputs)) {
+    if (
+      hasUnpairedSurrogate(input.source)
+      || utf8Bytes(input.source) > ARTIFACT_MANIFEST_BOUNDS.max_input_source_bytes
+    ) {
+      throw new ArtifactContractError("artifact_input_source_invalid");
+    }
+  }
+}
+
+export type Immutable<T> = T extends (...args: never[]) => unknown
+  ? T
+  : T extends readonly (infer Item)[]
+    ? readonly Immutable<Item>[]
+    : T extends object
+      ? { readonly [Key in keyof T]: Immutable<T[Key]> }
+      : T;
+
+function cloneAndFreeze<T>(value: T): Immutable<T> {
+  if (Array.isArray(value)) {
+    return Object.freeze(value.map((item) => cloneAndFreeze(item))) as Immutable<T>;
+  }
+  if (typeof value === "object" && value !== null) {
+    const clone = Object.fromEntries(
+      Object.entries(value).map(([key, item]) => [key, cloneAndFreeze(item)]),
+    );
+    return Object.freeze(clone) as Immutable<T>;
+  }
+  return value as Immutable<T>;
+}
+
+function canonicalizeArtifactDeclaration(value: unknown): unknown {
+  if (
+    typeof value !== "object"
+    || value === null
+    || Array.isArray(value)
+  ) {
+    return value;
+  }
+  const artifact = value as Record<string, unknown>;
+  const activation = artifact.agent_activation;
+  if (
+    artifact.contract_version !== 2
+    || typeof activation !== "object"
+    || activation === null
+    || Array.isArray(activation)
+  ) {
+    return value;
+  }
+  const policy = activation as Record<string, unknown>;
+  if (!Array.isArray(policy.authorities)) return value;
+  return {
+    ...artifact,
+    agent_activation: {
+      ...policy,
+      authorities: [...policy.authorities].sort(),
+    },
+  };
+}
+
+function parseWire<T>(
+  value: unknown,
+  validator: WireValidateFunction,
+  code: string,
+): Immutable<T> {
+  const candidate = cloneAndFreeze(value);
+  if (!validator(candidate)) throw new ArtifactContractError(code);
+  return candidate as Immutable<T>;
+}
+
+/** Validate a summary exactly as it crosses the public wire boundary. */
+export function parseArtifactSummaryWire(
+  value: unknown,
+): Immutable<ArtifactSummaryWire> {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    throw new ArtifactContractError("artifact_summary_invalid");
+  }
+  const validator = (value as Record<string, unknown>).contract_version === 1
+    ? validateSummaryV1
+    : validateSummaryV2;
+  return parseWire<ArtifactSummaryWire>(value, validator, "artifact_summary_invalid");
+}
+
+/**
+ * Project an internal Artifact record onto the canonical public summary shape.
+ * This is intentionally schema-driven so producers cannot grow a second,
+ * hand-maintained allowlist when the wire contract evolves.
+ */
+export function projectArtifactSummaryWire(
+  value: unknown,
+  contractVersion?: 1 | 2,
+): Immutable<ArtifactSummaryWire> {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    throw new ArtifactContractError("artifact_summary_invalid");
+  }
+  const row = value as Record<string, unknown>;
+  const version = contractVersion ?? (row.contract_version === 1 ? 1 : 2);
+  const schema = version === 1
+    ? catalog.schemas.artifact_summary_v1
+    : catalog.schemas.artifact_summary_v2;
+  const projected = Object.fromEntries(
+    Object.keys(schema.properties)
+      .filter((key) => row[key] !== undefined)
+      .map((key) => [key, row[key]]),
+  );
+  projected.contract_version = version;
+  return parseArtifactSummaryWire(projected);
+}
+
+export function parseArtifactExecutionSessionWire(
+  value: unknown,
+): Immutable<ArtifactExecutionSessionWire> {
+  const session = parseWire<ArtifactExecutionSessionWire>(
+    value,
+    validateExecutionSession,
+    "artifact_execution_session_invalid",
+  );
+  validateExecutionWindow(session);
+  return session;
+}
+
+export function parseArtifactExecutionRenewalWire(
+  value: unknown,
+): Immutable<ArtifactExecutionRenewalWire> {
+  const renewal = parseWire<ArtifactExecutionRenewalWire>(
+    value,
+    validateExecutionRenewal,
+    "artifact_execution_renewal_invalid",
+  );
+  validateExecutionWindow(renewal);
+  return renewal;
+}
+
+function validateExecutionWindow(value: {
+  lease_expires_at: string;
+  absolute_expires_at: string;
+}): void {
+  const lease = rfc3339Instant(value.lease_expires_at);
+  const absolute = rfc3339Instant(value.absolute_expires_at);
+  if (!lease || !absolute || compareInstants(lease, absolute) > 0) {
+    throw new ArtifactContractError("artifact_execution_window_invalid");
+  }
+}
+
+export function parseArtifactDeclaration(
+  value: unknown,
+): Immutable<ArtifactDeclaration> {
+  const candidate = cloneAndFreeze(value);
+  validateArtifact(candidate);
+  return cloneAndFreeze(
+    canonicalizeArtifactDeclaration(candidate),
+  ) as Immutable<ArtifactDeclaration>;
+}
+
+export function parseArtifactManifestDocument(
+  value: unknown,
+): Immutable<ArtifactManifestDocumentV2> {
+  const candidate = cloneAndFreeze(value);
+  if (!validateManifest(candidate)) {
+    if (
+      typeof candidate === "object"
+      && candidate !== null
+      && Array.isArray((candidate as Record<string, unknown>).artifacts)
+    ) {
+      for (const artifact of (candidate as { artifacts: readonly unknown[] }).artifacts) {
+        validateArtifact(artifact);
+      }
+    }
+    const first = validateManifest.errors?.[0];
+    throw new ArtifactContractError(
+      first ? declaredError(manifestErrorSchema, first) : "artifact_document_invalid",
+    );
+  }
+  const document = candidate as Immutable<ArtifactManifestDocumentV2>;
+  for (const artifact of document.artifacts) validateArtifact(artifact);
+  return cloneAndFreeze({
+    ...document,
+    artifacts: document.artifacts.map(canonicalizeArtifactDeclaration),
+  }) as Immutable<ArtifactManifestDocumentV2>;
+}
+
+export interface ArtifactTreeSummary {
+  scope: "root" | "input" | "all_inputs" | "static_share";
+  files: number;
+  bytes: number;
+  escaping_symlink: boolean;
+  secret_path: boolean;
+  reserved_path_collision: boolean;
+}
+
+export function validateArtifactTree(value: unknown): void {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    throw new ArtifactContractError("artifact_tree_invalid");
+  }
+  const summary = value as Record<string, unknown>;
+  if (!["root", "input", "all_inputs", "static_share"].includes(String(summary.scope))) {
+    throw new ArtifactContractError("artifact_tree_scope_invalid");
+  }
+  if (
+    !Number.isInteger(summary.files)
+    || !Number.isInteger(summary.bytes)
+    || (summary.files as number) < 0
+    || (summary.bytes as number) < 0
+    || typeof summary.escaping_symlink !== "boolean"
+    || typeof summary.secret_path !== "boolean"
+    || typeof summary.reserved_path_collision !== "boolean"
+  ) {
+    throw new ArtifactContractError("artifact_tree_invalid");
+  }
+  if (summary.escaping_symlink && ARTIFACT_TREE_BOUNDS.reject_symlinks_escaping_tree) {
+    throw new ArtifactContractError("artifact_tree_symlink_escape");
+  }
+  if (summary.secret_path && ARTIFACT_TREE_BOUNDS.reject_secret_paths) {
+    throw new ArtifactContractError("artifact_tree_secret_path");
+  }
+  if (summary.reserved_path_collision) {
+    throw new ArtifactContractError("artifact_tree_reserved_path_collision");
+  }
+  const scope = summary.scope as ArtifactTreeSummary["scope"];
+  const bound = ARTIFACT_TREE_BOUNDS[scope];
+  if ((summary.files as number) > bound.max_files) {
+    throw new ArtifactContractError("artifact_tree_files_exceeded");
+  }
+  if ((summary.bytes as number) > bound.max_bytes) {
+    throw new ArtifactContractError("artifact_tree_bytes_exceeded");
+  }
+}
+
+export function acceptsArtifactRootContentType(value: string): boolean {
+  const essence = value.split(";", 1)[0]?.trim().toLowerCase();
+  return essence === ARTIFACT_HTTP_CONTRACT.root_media_type_essence;
+}
+
+export type { ArtifactDeclarationV1, ArtifactDeclarationV2 };

package/node_modules/@dharta/contracts/src/index.ts

@@ -0,0 +1,5 @@
+export * from "./wire-events.js";
+export * from "./activity.js";
+export * from "./tasks.js";
+export * from "./artifact-runtime.js";
+export * from "./model-auth.js";

package/node_modules/@dharta/contracts/src/model-auth.ts

@@ -0,0 +1,82 @@
+export const MODEL_AUTH_CREDENTIAL_KINDS = [
+  "api_key",
+  "oauth_session",
+  "provider_managed_session",
+  "workload_identity",
+] as const;
+
+export const MODEL_AUTH_FUNDING_SOURCES = [
+  "api_usage",
+  "subscription_entitlement",
+  "enterprise_entitlement",
+  "platform",
+] as const;
+
+export const MODEL_AUTH_OWNER_KINDS = ["organization", "individual", "install", "platform"] as const;
+
+export const MODEL_AUTH_STORAGE_KINDS = [
+  "control_plane_encrypted",
+  "install_local_ref",
+  "os_keyring",
+  "provider_client_owned",
+] as const;
+
+export const MODEL_AUTH_EXECUTION_SCOPES = [
+  "local",
+  "private_interactive",
+  "background",
+  "shared",
+  "public",
+] as const;
+
+export type ModelAuthCredentialKind = (typeof MODEL_AUTH_CREDENTIAL_KINDS)[number];
+export type ModelAuthFundingSource = (typeof MODEL_AUTH_FUNDING_SOURCES)[number];
+export type ModelAuthOwnerKind = (typeof MODEL_AUTH_OWNER_KINDS)[number];
+export type ModelAuthStorageKind = (typeof MODEL_AUTH_STORAGE_KINDS)[number];
+export type ModelAuthExecutionScope = (typeof MODEL_AUTH_EXECUTION_SCOPES)[number];
+
+export interface ModelAuthCapability {
+  id: string;
+  provider: string;
+  credential_kind: ModelAuthCredentialKind;
+  funding_source: ModelAuthFundingSource;
+  owner_kinds: readonly ModelAuthOwnerKind[];
+  storage_kinds: readonly ModelAuthStorageKind[];
+  execution_scopes: readonly ModelAuthExecutionScope[];
+  admission: "enabled" | "disabled";
+  runtime_switch: string;
+  adapter: string | null;
+}
+
+export const MODEL_AUTH_REASON_CODES = [
+  "model_auth_missing",
+  "model_auth_expiring",
+  "model_auth_expired",
+  "model_auth_refresh_failed",
+  "model_auth_reauthorization_required",
+  "model_auth_refresh_outcome_indeterminate",
+  "model_auth_entitlement_exhausted",
+  "model_auth_revoked",
+  "model_auth_capability_disabled",
+  "model_auth_scope_ineligible",
+  "model_auth_funding_selection_required",
+  "model_auth_new_session_required",
+  "model_auth_account_mismatch",
+  "model_auth_adapter_unavailable",
+  "model_auth_misconfigured",
+  "model_auth_provider_unavailable",
+] as const;
+
+export type ModelAuthReasonCode = (typeof MODEL_AUTH_REASON_CODES)[number];
+
+export interface ModelAuthReason {
+  code: ModelAuthReasonCode;
+  fails_turn: boolean;
+  stage: "authorization" | "dispatch" | "policy" | "setup";
+  retry_class:
+    | "after_policy_change"
+    | "after_reauthorization"
+    | "never"
+    | "operator_intervention"
+    | "provider_later";
+}