@dbx-tools/appkit-generator 0.0.0-stage → 0.9.136

package/src/namespace.ts

@@ -0,0 +1,192 @@
+/**
+ * Per-user Unity Catalog namespace derivation and provisioning.
+ *
+ * @module
+ */
+
+import {
+  ConfigurationError,
+  createWorkspaceClient,
+  getExecutionContext,
+  type WorkspaceClient,
+} from "@databricks/appkit";
+import { databricks } from "@dbx-tools/appkit";
+import { errorUtils, hash, stringUtils } from "@dbx-tools/shared-core";
+import {
+  GeneratedSchemaSchema,
+  type GeneratedSchema,
+  type GeneratorRequest,
+} from "@dbx-tools/shared-generator/workflow";
+
+const OWNER_DIGEST_PROPERTY = "dbx_tools.generator.owner_digest";
+const REQUEST_DIGEST_PROPERTY = "dbx_tools.generator.request_digest";
+
+/** Inputs needed to provision one deterministic generated schema. */
+export interface ProvisionSchemaInput {
+  /** Configured parent catalog. */
+  catalog: string;
+  /** Company and purpose used to derive the schema name. */
+  request: Pick<GeneratorRequest, "company" | "purpose">;
+}
+
+/** Trusted user identity and clients resolved from the active AppKit request. */
+export interface GeneratorIdentity {
+  /** OBO workspace client. */
+  userClient: WorkspaceClient;
+  /** Service-principal workspace client. */
+  serviceClient: WorkspaceClient;
+  /** Trusted Databricks user name. */
+  principal: string;
+  /** Trusted stable user id. */
+  userId: string;
+}
+
+/** Derive a readable, bounded schema name with collision-resistant overflow. */
+export function generatorSchemaName(principal: string, company: string, purpose: string): string {
+  const base = stringUtils.toIdentifierWithOptions(
+    {
+      delimiter: "_",
+      omitEmailDomain: true,
+      maxLength: 96,
+      truncateStrategy: "hash",
+      truncateHashLength: 8,
+    },
+    principal,
+    company,
+    purpose,
+  );
+  return /^[a-z]/.test(base) ? base : `u_${base}`;
+}
+
+/** Resolve the active OBO caller and a separate app service-principal client. */
+export async function resolveGeneratorIdentity(): Promise<GeneratorIdentity> {
+  const context = getExecutionContext();
+  if (!("userId" in context)) {
+    throw new ConfigurationError("Generator operations require an on-behalf-of user context");
+  }
+  const current = await context.client.currentUser.me();
+  const principal = stringUtils.trimToNull(current.userName);
+  if (!principal) {
+    throw new ConfigurationError("The current Databricks user has no userName");
+  }
+  return {
+    userClient: context.client,
+    serviceClient: createWorkspaceClient(),
+    principal,
+    userId: context.userId,
+  };
+}
+
+/** Return an existing schema, treating only a genuine not-found response as absent. */
+async function getSchema(
+  client: WorkspaceClient,
+  fullName: string,
+): Promise<
+  | Awaited<ReturnType<ReturnType<WorkspaceClient["toLegacyWorkspaceClient"]>["schemas"]["get"]>>
+  | undefined
+> {
+  try {
+    return await client.toLegacyWorkspaceClient().schemas.get({ full_name: fullName });
+  } catch (cause) {
+    const context = errorUtils.errorContext(cause);
+    if (context.hasStatusCode(404) || context.hasMessage("does not exist")) return undefined;
+    throw cause;
+  }
+}
+
+/** Verify that an existing deterministic schema belongs to this user and request. */
+function assertSchemaMarkers(
+  schema: { properties?: Record<string, string> },
+  ownerDigest: string,
+  requestDigest: string,
+  fullName: string,
+): void {
+  if (
+    schema.properties?.[OWNER_DIGEST_PROPERTY] !== ownerDigest ||
+    schema.properties?.[REQUEST_DIGEST_PROPERTY] !== requestDigest
+  ) {
+    throw new ConfigurationError(
+      `Generator schema ${fullName} already exists with different ownership markers`,
+    );
+  }
+}
+
+/**
+ * Check-create-recheck one marked schema as the app service principal, then
+ * grant the OBO user full schema control while retaining SP ownership.
+ */
+export async function provisionGeneratorSchema(
+  input: ProvisionSchemaInput,
+  signal?: AbortSignal,
+): Promise<GeneratedSchema> {
+  const identity = await resolveGeneratorIdentity();
+  return provisionGeneratorSchemaWithIdentity(input, identity, signal);
+}
+
+/** Provision with explicit trusted clients, for plugin reuse and isolated tests. */
+export async function provisionGeneratorSchemaWithIdentity(
+  input: ProvisionSchemaInput,
+  identity: GeneratorIdentity,
+  signal?: AbortSignal,
+): Promise<GeneratedSchema> {
+  const catalog = stringUtils.trimToNull(input.catalog);
+  if (!catalog) throw new ConfigurationError("GENERATOR_CATALOG is required");
+
+  const schemaName = generatorSchemaName(
+    identity.principal,
+    input.request.company,
+    input.request.purpose,
+  );
+  const fullName = `${catalog}.${schemaName}`;
+  const ownerDigest = hash.fnvHash(identity.userId);
+  const requestDigest = hash.fnvHash(identity.userId, input.request.company, input.request.purpose);
+  const context = signal ? databricks.toContext(signal) : undefined;
+
+  await identity.userClient.toLegacyWorkspaceClient().catalogs.get({ name: catalog });
+
+  let schema = await getSchema(identity.serviceClient, fullName);
+  if (!schema) {
+    try {
+      await identity.serviceClient.toLegacyWorkspaceClient().schemas.create(
+        {
+          catalog_name: catalog,
+          name: schemaName,
+          comment: `Generated demo assets for ${identity.principal}`,
+          properties: {
+            [OWNER_DIGEST_PROPERTY]: ownerDigest,
+            [REQUEST_DIGEST_PROPERTY]: requestDigest,
+          },
+        },
+        context,
+      );
+    } catch (cause) {
+      if (!errorUtils.errorContext(cause).hasMessage("already exists")) throw cause;
+    }
+    schema = await getSchema(identity.serviceClient, fullName);
+  }
+  if (!schema) {
+    throw ConfigurationError.resourceNotFound("Generator schema", fullName);
+  }
+  assertSchemaMarkers(schema, ownerDigest, requestDigest, fullName);
+
+  await identity.serviceClient.toLegacyWorkspaceClient().grants.update(
+    {
+      securable_type: "SCHEMA",
+      full_name: fullName,
+      changes: [
+        {
+          principal: identity.principal,
+          add: ["ALL_PRIVILEGES", "MANAGE"],
+        },
+      ],
+    },
+    context,
+  );
+
+  return GeneratedSchemaSchema.parse({
+    catalog,
+    schema: schemaName,
+    fullName,
+    principal: identity.principal,
+  });
+}

package/src/operations.ts

@@ -0,0 +1,171 @@
+/**
+ * Reusable generator operations shared by tools and workflow steps.
+ *
+ * @module
+ */
+
+import { ConfigurationError } from "@databricks/appkit";
+import type { BrandGenerationRequest, BrandPackage } from "@dbx-tools/shared-generator/brand";
+import type { KpiResearchRequest, KpiResearchResult } from "@dbx-tools/shared-generator/kpi";
+import type {
+  CreateGeneratorPresentationRequest,
+  GeneratedDashboard,
+  GeneratedGenieSpace,
+  GeneratedSchema,
+  GeneratorPlan,
+  MaterializeGeneratorDataRequest,
+  MaterializedGeneratorData,
+  PlanGeneratorDataRequest,
+  ProvisionGeneratorSchemaRequest,
+} from "@dbx-tools/shared-generator/workflow";
+import type { ResolvedGeneratorConfig } from "./config.ts";
+import { createGeneratorDashboard } from "./dashboard.ts";
+import { materializeGeneratorData } from "./data.ts";
+import { generateBrandPackage } from "./generate.ts";
+import { createGeneratorGenieSpace } from "./genie.ts";
+import { researchKpis } from "./kpi.ts";
+import { provisionGeneratorSchema } from "./namespace.ts";
+import { planGeneratorData } from "./plan.ts";
+import type { BrandProgressReporter, BrandResearchClient } from "./research.ts";
+
+/** Runtime dependencies captured by one generator plugin instance. */
+export interface GeneratorOperationsOptions {
+  /** Resolved generator configuration. */
+  config: ResolvedGeneratorConfig;
+  /** Registered web-search plugin operations. */
+  researchClient: BrandResearchClient;
+}
+
+/** One behavior owner for every generator tool and workflow step. */
+export class GeneratorOperations {
+  private readonly config: ResolvedGeneratorConfig;
+  private readonly researchClient: BrandResearchClient;
+
+  /** Create operations over one isolated plugin runtime. */
+  constructor(options: GeneratorOperationsOptions) {
+    this.config = options.config;
+    this.researchClient = options.researchClient;
+  }
+
+  /** Generate portable brand assets without KPI research or Databricks writes. */
+  generateBrand(
+    request: BrandGenerationRequest,
+    signal?: AbortSignal,
+    onProgress?: BrandProgressReporter,
+  ): Promise<BrandPackage> {
+    return generateBrandPackage(
+      request,
+      {
+        client: this.researchClient,
+        ...(this.config.model ? { model: this.config.model } : {}),
+        maxSources: this.config.maxSources,
+        sourceMaxLength: this.config.sourceMaxLength,
+        ...(onProgress ? { onProgress } : {}),
+      },
+      signal,
+    );
+  }
+
+  /** Research KPIs independently of any mutation workflow. */
+  researchKpis(request: KpiResearchRequest, signal?: AbortSignal): Promise<KpiResearchResult> {
+    return researchKpis(
+      request,
+      {
+        client: this.researchClient,
+        maxSources: this.config.maxSources,
+        sourceMaxLength: this.config.sourceMaxLength,
+        ...(this.config.model ? { model: this.config.model } : {}),
+      },
+      signal,
+    );
+  }
+
+  /** Build a typed deterministic data plan. */
+  planData(request: PlanGeneratorDataRequest, signal?: AbortSignal): Promise<GeneratorPlan> {
+    return planGeneratorData(
+      {
+        ...request,
+        ...(this.config.model ? { model: this.config.model } : {}),
+      },
+      signal,
+    );
+  }
+
+  /** Provision the active OBO user's deterministic schema. */
+  provisionSchema(
+    request: ProvisionGeneratorSchemaRequest,
+    signal?: AbortSignal,
+  ): Promise<GeneratedSchema> {
+    return provisionGeneratorSchema(
+      {
+        catalog: this.requiredCatalog(),
+        request: request.request,
+      },
+      signal,
+    );
+  }
+
+  /** Materialize generated data and validate its KPI aggregates. */
+  materializeData(
+    request: MaterializeGeneratorDataRequest,
+    signal?: AbortSignal,
+  ): Promise<MaterializedGeneratorData> {
+    return materializeGeneratorData(
+      request.location,
+      request.plan,
+      this.requiredWarehouseId(),
+      signal,
+    );
+  }
+
+  /** Create and publish a dashboard with automatic companion Genie. */
+  createDashboard(
+    request: CreateGeneratorPresentationRequest,
+    signal?: AbortSignal,
+  ): Promise<GeneratedDashboard> {
+    return createGeneratorDashboard(
+      {
+        location: request.location,
+        plan: request.plan,
+        brand: request.brand.brand,
+        company: request.request.company,
+        purpose: request.request.purpose,
+        warehouseId: this.requiredWarehouseId(),
+      },
+      signal,
+    );
+  }
+
+  /** Create a standalone Genie space for no-dashboard runs. */
+  createGenie(
+    request: CreateGeneratorPresentationRequest,
+    signal?: AbortSignal,
+  ): Promise<GeneratedGenieSpace> {
+    return createGeneratorGenieSpace(
+      {
+        location: request.location,
+        plan: request.plan,
+        company: request.request.company,
+        purpose: request.request.purpose,
+        warehouseId: this.requiredWarehouseId(),
+      },
+      signal,
+    );
+  }
+
+  /** Configured catalog or a deployment-time configuration error. */
+  private requiredCatalog(): string {
+    if (!this.config.catalog) {
+      throw new ConfigurationError("GENERATOR_CATALOG is required for generator mutations");
+    }
+    return this.config.catalog;
+  }
+
+  /** Configured SQL warehouse or a deployment-time configuration error. */
+  private requiredWarehouseId(): string {
+    if (!this.config.warehouseId) {
+      throw new ConfigurationError("DATABRICKS_WAREHOUSE_ID is required for generator mutations");
+    }
+    return this.config.warehouseId;
+  }
+}

package/src/palette.ts

@@ -0,0 +1,81 @@
+/**
+ * Accessibility normalization for model-generated interface palettes.
+ *
+ * @module
+ */
+
+import type { GeneratedBrandProfile } from "./schema.ts";
+
+interface Rgb {
+  red: number;
+  green: number;
+  blue: number;
+}
+
+/** Expand a schema-validated hex color into RGB channels. */
+function hexToRgb(color: string): Rgb {
+  const hex = color.slice(1);
+  const expanded =
+    hex.length === 3 ? [...hex].map((value) => `${value}${value}`).join("") : hex.slice(0, 6);
+  return {
+    red: Number.parseInt(expanded.slice(0, 2), 16),
+    green: Number.parseInt(expanded.slice(2, 4), 16),
+    blue: Number.parseInt(expanded.slice(4, 6), 16),
+  };
+}
+
+/** Serialize RGB channels as a six-digit uppercase hex color. */
+function rgbToHex(color: Rgb): string {
+  const channel = (value: number) => Math.round(value).toString(16).padStart(2, "0").toUpperCase();
+  return `#${channel(color.red)}${channel(color.green)}${channel(color.blue)}`;
+}
+
+/** WCAG relative luminance for one sRGB color. */
+function relativeLuminance(color: Rgb): number {
+  const channel = (value: number) => {
+    const normalized = value / 255;
+    return normalized <= 0.04045 ? normalized / 12.92 : ((normalized + 0.055) / 1.055) ** 2.4;
+  };
+  return 0.2126 * channel(color.red) + 0.7152 * channel(color.green) + 0.0722 * channel(color.blue);
+}
+
+/** WCAG contrast ratio between two schema-valid hex colors. */
+export function colorContrastRatio(foreground: string, background: string): number {
+  const first = relativeLuminance(hexToRgb(foreground));
+  const second = relativeLuminance(hexToRgb(background));
+  const lighter = Math.max(first, second);
+  const darker = Math.min(first, second);
+  return (lighter + 0.05) / (darker + 0.05);
+}
+
+/** Blend a color toward black or white past the AA threshold with rendering margin. */
+function ensureContrast(color: string, background: string, minimum = 5): string {
+  if (colorContrastRatio(color, background) >= minimum) return color;
+  const source = hexToRgb(color);
+  const backgroundIsLight = relativeLuminance(hexToRgb(background)) > 0.5;
+  const target = backgroundIsLight ? 0 : 255;
+  for (let amount = 0.05; amount <= 1; amount += 0.05) {
+    const candidate = rgbToHex({
+      red: source.red + (target - source.red) * amount,
+      green: source.green + (target - source.green) * amount,
+      blue: source.blue + (target - source.blue) * amount,
+    });
+    if (colorContrastRatio(candidate, background) >= minimum) return candidate;
+  }
+  return backgroundIsLight ? "#000000" : "#FFFFFF";
+}
+
+/** Make generated text and action colors readable against the page background. */
+export function normalizeBrandPalette(profile: GeneratedBrandProfile): GeneratedBrandProfile {
+  const background = profile.colors.background;
+  return {
+    ...profile,
+    colors: {
+      ...profile.colors,
+      primary: ensureContrast(profile.colors.primary, background),
+      primaryHover: ensureContrast(profile.colors.primaryHover, background),
+      foreground: ensureContrast(profile.colors.foreground, background),
+      muted: ensureContrast(profile.colors.muted, background),
+    },
+  };
+}

package/src/plan.ts

@@ -0,0 +1,59 @@
+/**
+ * Structured demo-data planning from brand and KPI research.
+ *
+ * @module
+ */
+
+import type { BrandPackage } from "@dbx-tools/shared-generator/brand";
+import type { KpiResearchResult } from "@dbx-tools/shared-generator/kpi";
+import {
+  GeneratorPlanSchema,
+  type GeneratorPlan,
+  type GeneratorRequest,
+} from "@dbx-tools/shared-generator/workflow";
+import { generateStructured } from "./structured.ts";
+
+/** Inputs for deterministic demo-data planning. */
+export interface PlanGeneratorDataInput {
+  /** Validated workflow request. */
+  request: GeneratorRequest;
+  /** Researched brand package. */
+  brand: BrandPackage;
+  /** Evidence-backed KPI research. */
+  kpiResearch: KpiResearchResult;
+  /** Optional model preference. */
+  model?: string;
+}
+
+/** Build a constrained plan that can be compiled without model-authored SQL. */
+export async function planGeneratorData(
+  input: PlanGeneratorDataInput,
+  signal?: AbortSignal,
+): Promise<GeneratorPlan> {
+  const generated = await generateStructured({
+    id: "demo-data-planner",
+    instructions: [
+      "Plan one denormalized Delta fact table for a realistic business demo.",
+      "Use only the supplied generator kinds and KPI aggregations.",
+      "Include an id column, a date column, two to six useful categories,",
+      "numeric columns needed by every KPI, and a measurable anomaly.",
+      "Do not write SQL. Do not invent unsupported generator fields.",
+    ].join(" "),
+    prompt: JSON.stringify(
+      {
+        request: input.request,
+        brand: input.brand.brand,
+        kpis: input.kpiResearch.kpis,
+      },
+      null,
+      2,
+    ),
+    schema: GeneratorPlanSchema,
+    ...(input.model ? { model: input.model } : {}),
+    ...(signal ? { signal } : {}),
+  });
+  return GeneratorPlanSchema.parse({
+    ...generated,
+    rowCount: input.request.rowCount,
+  });
+}