@databricks/appkit 0.59.0 → 0.61.0

package/dist/cli/commands/registry/config-plan.js

@@ -0,0 +1,110 @@
+import { fieldOrigin, isValidEnvName } from "./requirements.js";
+
+//#region src/cli/commands/registry/config-plan.ts
+const BINDING_SPECS = {
+	sql_warehouse: {
+		variableFields: ["id"],
+		bindingFields: ["id"],
+		variable: (f) => `sql_warehouse_${f}`
+	},
+	postgres: {
+		variableFields: [
+			"project",
+			"branch",
+			"database"
+		],
+		bindingFields: ["branch", "database"],
+		variable: (f) => `postgres_${f}`
+	}
+};
+/**
+* Builds the deploy-config plan for a set of resource rows. `values` supplies
+* the concrete values for the target-level bundle variables (keyed by the
+* manifest field's env var name for env-bearing fields, else by field key);
+* missing values leave the variable value undefined.
+*/
+function buildConfigPlan(rows, values = {}) {
+	const appYamlEnv = [];
+	const bundleVariables = [];
+	const resourceBindings = [];
+	const unverifiedTypes = [];
+	const seenEnv = /* @__PURE__ */ new Set();
+	const seenVar = /* @__PURE__ */ new Set();
+	for (const row of rows) {
+		const resourceKey = row.resourceKey ?? row.type;
+		for (const field of row.fields) {
+			if (!field.env || fieldOrigin(field) === "platform") continue;
+			if (!isValidEnvName(field.env)) continue;
+			if (seenEnv.has(field.env)) continue;
+			seenEnv.add(field.env);
+			appYamlEnv.push({
+				name: field.env,
+				valueFrom: resourceKey
+			});
+		}
+		const spec = BINDING_SPECS[row.type];
+		if (!spec) {
+			if (!unverifiedTypes.includes(row.type)) unverifiedTypes.push(row.type);
+			continue;
+		}
+		for (const fieldKey of spec.variableFields) {
+			const varName = spec.variable(fieldKey);
+			if (seenVar.has(varName)) continue;
+			seenVar.add(varName);
+			const field = row.fields.find((f) => f.key === fieldKey);
+			const valueKey = field?.env ?? fieldKey;
+			bundleVariables.push({
+				name: varName,
+				description: field?.description,
+				value: values[valueKey] ?? field?.value
+			});
+		}
+		const fields = {};
+		for (const fieldKey of spec.bindingFields) fields[fieldKey] = `\${var.${spec.variable(fieldKey)}}`;
+		resourceBindings.push({
+			name: resourceKey,
+			type: row.type,
+			permission: row.permission,
+			fields
+		});
+	}
+	return {
+		appYamlEnv,
+		bundleVariables,
+		resourceBindings,
+		unverifiedTypes
+	};
+}
+/**
+* Binding fields that carry a bundle-variable value but have no `env` name and
+* no static default — so they're invisible to collectEnvNeeds and must be
+* collected separately (keyed by fieldKey) to produce a valid databricks.yml.
+*/
+function collectBindingValueNeeds(rows) {
+	const needs = [];
+	const seen = /* @__PURE__ */ new Set();
+	for (const row of rows) {
+		const spec = BINDING_SPECS[row.type];
+		if (!spec) continue;
+		for (const fieldKey of spec.variableFields) {
+			const field = row.fields.find((f) => f.key === fieldKey);
+			if (field?.env || field?.value !== void 0) continue;
+			if (seen.has(fieldKey)) continue;
+			seen.add(fieldKey);
+			needs.push({
+				fieldKey,
+				resourceType: row.type,
+				description: field?.description
+			});
+		}
+	}
+	return needs;
+}
+/** True when the plan has any deploy-config content to write. */
+function planHasContent(plan) {
+	return plan.appYamlEnv.length > 0 || plan.bundleVariables.length > 0 || plan.resourceBindings.length > 0;
+}
+
+//#endregion
+export { buildConfigPlan, collectBindingValueNeeds, planHasContent };
+//# sourceMappingURL=config-plan.js.map

package/dist/cli/commands/registry/config-plan.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config-plan.js","names":[],"sources":["../../../../src/cli/commands/registry/config-plan.ts"],"sourcesContent":["import type { AppYamlEnvEntry, ResourceBinding } from \"../../deploy-config\";\nimport {\n  fieldOrigin,\n  isValidEnvName,\n  type ResourceRequirementRow,\n} from \"./requirements\";\n\n/**\n * Deploy-config generation for a plugin's resources, reproducing what\n * `databricks apps init` renders. Verified byte-for-byte against golden\n * fixtures (see __fixtures__/) for the resource types listed in\n * {@link BINDING_SPECS}. Unverified types degrade safely: their env entries\n * are still produced (that shape is uniform), but the databricks.yml resource\n * binding is skipped with a warning rather than guessed.\n */\n\n/** A `databricks.yml` top-level bundle variable. */\nexport interface BundleVariable {\n  name: string;\n  description?: string;\n  /** The value placed under targets.default.variables. */\n  value?: string;\n}\n\nexport interface ConfigPlan {\n  appYamlEnv: AppYamlEnvEntry[];\n  bundleVariables: BundleVariable[];\n  resourceBindings: ResourceBinding[];\n  /** Resource types encountered that have no verified binding spec. */\n  unverifiedTypes: string[];\n}\n\n/**\n * Per-type rules for producing databricks.yml bundle variables and the app\n * resource binding. Only types verified against golden fixtures appear here.\n *\n * - `variableFields`: field keys that become bundle variables (a superset of\n *   the binding fields; e.g. postgres declares project+branch+database).\n * - `bindingFields`: field keys included in the resource binding (a subset;\n *   e.g. postgres binds branch+database but not project).\n * - `variable(field)`: the bundle-variable name for a given field key.\n */\ninterface BindingSpec {\n  variableFields: string[];\n  bindingFields: string[];\n  variable: (fieldKey: string) => string;\n}\n\nconst BINDING_SPECS: Record<string, BindingSpec> = {\n  // Verified against __fixtures__/analytics.\n  sql_warehouse: {\n    variableFields: [\"id\"],\n    bindingFields: [\"id\"],\n    // fixture: variable is `sql_warehouse_id`\n    variable: (f) => `sql_warehouse_${f}`,\n  },\n  // Verified against __fixtures__/lakebase.\n  postgres: {\n    variableFields: [\"project\", \"branch\", \"database\"],\n    bindingFields: [\"branch\", \"database\"],\n    // fixture: variables are `postgres_<fieldKey>` (project/branch/database)\n    variable: (f) => `postgres_${f}`,\n  },\n};\n\n/**\n * Builds the deploy-config plan for a set of resource rows. `values` supplies\n * the concrete values for the target-level bundle variables (keyed by the\n * manifest field's env var name for env-bearing fields, else by field key);\n * missing values leave the variable value undefined.\n */\nexport function buildConfigPlan(\n  rows: ResourceRequirementRow[],\n  values: Record<string, string> = {},\n): ConfigPlan {\n  const appYamlEnv: AppYamlEnvEntry[] = [];\n  const bundleVariables: BundleVariable[] = [];\n  const resourceBindings: ResourceBinding[] = [];\n  const unverifiedTypes: string[] = [];\n  const seenEnv = new Set<string>();\n  const seenVar = new Set<string>();\n\n  for (const row of rows) {\n    // app.yaml env: every env-bearing field maps to valueFrom = resourceKey,\n    // except platform-injected fields (the platform provides those directly).\n    const resourceKey = row.resourceKey ?? row.type;\n    for (const field of row.fields) {\n      if (!field.env || fieldOrigin(field) === \"platform\") continue;\n      // env names are untrusted manifest data emitted into app.yaml — drop\n      // anything that isn't a plain env identifier (mirrors the .env guard).\n      if (!isValidEnvName(field.env)) continue;\n      if (seenEnv.has(field.env)) continue;\n      seenEnv.add(field.env);\n      appYamlEnv.push({ name: field.env, valueFrom: resourceKey });\n    }\n\n    const spec = BINDING_SPECS[row.type];\n    if (!spec) {\n      if (!unverifiedTypes.includes(row.type)) unverifiedTypes.push(row.type);\n      continue;\n    }\n\n    // Bundle variables (superset of binding fields for this type).\n    for (const fieldKey of spec.variableFields) {\n      const varName = spec.variable(fieldKey);\n      if (seenVar.has(varName)) continue;\n      seenVar.add(varName);\n      const field = row.fields.find((f) => f.key === fieldKey);\n      const valueKey = field?.env ?? fieldKey;\n      bundleVariables.push({\n        name: varName,\n        description: field?.description,\n        value: values[valueKey] ?? field?.value,\n      });\n    }\n\n    // Resource binding: only the spec's binding fields, referencing ${var.X}.\n    const fields: Record<string, string> = {};\n    for (const fieldKey of spec.bindingFields) {\n      fields[fieldKey] = `\\${var.${spec.variable(fieldKey)}}`;\n    }\n    resourceBindings.push({\n      name: resourceKey,\n      type: row.type,\n      permission: row.permission,\n      fields,\n    });\n  }\n\n  return { appYamlEnv, bundleVariables, resourceBindings, unverifiedTypes };\n}\n\n/**\n * A bundle-variable value the user must supply that the .env reconciliation\n * flow can't collect — a binding field with NO `env` name (e.g. postgres\n * project/branch/database). Without collecting these, databricks.yml declares\n * `${var.postgres_branch}` but never assigns it, and `bundle validate` fails.\n * Keyed by `fieldKey` (matching how buildConfigPlan looks up `values`).\n */\nexport interface BindingValueNeed {\n  fieldKey: string;\n  resourceType: string;\n  description?: string;\n}\n\n/**\n * Binding fields that carry a bundle-variable value but have no `env` name and\n * no static default — so they're invisible to collectEnvNeeds and must be\n * collected separately (keyed by fieldKey) to produce a valid databricks.yml.\n */\nexport function collectBindingValueNeeds(\n  rows: ResourceRequirementRow[],\n): BindingValueNeed[] {\n  const needs: BindingValueNeed[] = [];\n  const seen = new Set<string>();\n  for (const row of rows) {\n    const spec = BINDING_SPECS[row.type];\n    if (!spec) continue;\n    for (const fieldKey of spec.variableFields) {\n      const field = row.fields.find((f) => f.key === fieldKey);\n      // Skip fields that already flow through .env (have an env name) or carry\n      // a static default — those get their value elsewhere.\n      if (field?.env || field?.value !== undefined) continue;\n      if (seen.has(fieldKey)) continue;\n      seen.add(fieldKey);\n      needs.push({\n        fieldKey,\n        resourceType: row.type,\n        description: field?.description,\n      });\n    }\n  }\n  return needs;\n}\n\n/** True when the plan has any deploy-config content to write. */\nexport function planHasContent(plan: ConfigPlan): boolean {\n  return (\n    plan.appYamlEnv.length > 0 ||\n    plan.bundleVariables.length > 0 ||\n    plan.resourceBindings.length > 0\n  );\n}\n"],"mappings":";;;AAgDA,MAAM,gBAA6C;CAEjD,eAAe;EACb,gBAAgB,CAAC,KAAK;EACtB,eAAe,CAAC,KAAK;EAErB,WAAW,MAAM,iBAAiB;EACnC;CAED,UAAU;EACR,gBAAgB;GAAC;GAAW;GAAU;GAAW;EACjD,eAAe,CAAC,UAAU,WAAW;EAErC,WAAW,MAAM,YAAY;EAC9B;CACF;;;;;;;AAQD,SAAgB,gBACd,MACA,SAAiC,EAAE,EACvB;CACZ,MAAM,aAAgC,EAAE;CACxC,MAAM,kBAAoC,EAAE;CAC5C,MAAM,mBAAsC,EAAE;CAC9C,MAAM,kBAA4B,EAAE;CACpC,MAAM,0BAAU,IAAI,KAAa;CACjC,MAAM,0BAAU,IAAI,KAAa;AAEjC,MAAK,MAAM,OAAO,MAAM;EAGtB,MAAM,cAAc,IAAI,eAAe,IAAI;AAC3C,OAAK,MAAM,SAAS,IAAI,QAAQ;AAC9B,OAAI,CAAC,MAAM,OAAO,YAAY,MAAM,KAAK,WAAY;AAGrD,OAAI,CAAC,eAAe,MAAM,IAAI,CAAE;AAChC,OAAI,QAAQ,IAAI,MAAM,IAAI,CAAE;AAC5B,WAAQ,IAAI,MAAM,IAAI;AACtB,cAAW,KAAK;IAAE,MAAM,MAAM;IAAK,WAAW;IAAa,CAAC;;EAG9D,MAAM,OAAO,cAAc,IAAI;AAC/B,MAAI,CAAC,MAAM;AACT,OAAI,CAAC,gBAAgB,SAAS,IAAI,KAAK,CAAE,iBAAgB,KAAK,IAAI,KAAK;AACvE;;AAIF,OAAK,MAAM,YAAY,KAAK,gBAAgB;GAC1C,MAAM,UAAU,KAAK,SAAS,SAAS;AACvC,OAAI,QAAQ,IAAI,QAAQ,CAAE;AAC1B,WAAQ,IAAI,QAAQ;GACpB,MAAM,QAAQ,IAAI,OAAO,MAAM,MAAM,EAAE,QAAQ,SAAS;GACxD,MAAM,WAAW,OAAO,OAAO;AAC/B,mBAAgB,KAAK;IACnB,MAAM;IACN,aAAa,OAAO;IACpB,OAAO,OAAO,aAAa,OAAO;IACnC,CAAC;;EAIJ,MAAM,SAAiC,EAAE;AACzC,OAAK,MAAM,YAAY,KAAK,cAC1B,QAAO,YAAY,UAAU,KAAK,SAAS,SAAS,CAAC;AAEvD,mBAAiB,KAAK;GACpB,MAAM;GACN,MAAM,IAAI;GACV,YAAY,IAAI;GAChB;GACD,CAAC;;AAGJ,QAAO;EAAE;EAAY;EAAiB;EAAkB;EAAiB;;;;;;;AAqB3E,SAAgB,yBACd,MACoB;CACpB,MAAM,QAA4B,EAAE;CACpC,MAAM,uBAAO,IAAI,KAAa;AAC9B,MAAK,MAAM,OAAO,MAAM;EACtB,MAAM,OAAO,cAAc,IAAI;AAC/B,MAAI,CAAC,KAAM;AACX,OAAK,MAAM,YAAY,KAAK,gBAAgB;GAC1C,MAAM,QAAQ,IAAI,OAAO,MAAM,MAAM,EAAE,QAAQ,SAAS;AAGxD,OAAI,OAAO,OAAO,OAAO,UAAU,OAAW;AAC9C,OAAI,KAAK,IAAI,SAAS,CAAE;AACxB,QAAK,IAAI,SAAS;AAClB,SAAM,KAAK;IACT;IACA,cAAc,IAAI;IAClB,aAAa,OAAO;IACrB,CAAC;;;AAGN,QAAO;;;AAIT,SAAgB,eAAe,MAA2B;AACxD,QACE,KAAK,WAAW,SAAS,KACzB,KAAK,gBAAgB,SAAS,KAC9B,KAAK,iBAAiB,SAAS"}

package/dist/cli/commands/registry/config-writer.js

@@ -0,0 +1,176 @@
+import { APP_YAML_FILE, DATABRICKS_YML_FILE, bindingToNode } from "../../deploy-config.js";
+import { planHasContent } from "./config-plan.js";
+import fs from "node:fs";
+import path from "node:path";
+import pc from "picocolors";
+import { spawnSync } from "node:child_process";
+import { parseDocument } from "yaml";
+
+//#region src/cli/commands/registry/config-writer.ts
+/** Reads and parses a YAML file into a Document, or a fresh doc if absent. */
+function loadDoc(file) {
+	if (fs.existsSync(file)) return parseDocument(fs.readFileSync(file, "utf-8"));
+	return parseDocument("");
+}
+/**
+* Additively patches `app.yaml`'s `env:` list with entries not already present
+* (matched by `name`). Returns the names added.
+*/
+function patchAppYaml(file, entries) {
+	if (entries.length === 0) return [];
+	const doc = loadDoc(file);
+	let seq = doc.get("env");
+	if (!seq || typeof seq.add !== "function") {
+		doc.set("env", doc.createNode([]));
+		seq = doc.get("env");
+	}
+	const existingNames = /* @__PURE__ */ new Set();
+	for (const item of seq.items) {
+		const name = item?.get?.("name");
+		if (typeof name === "string") existingNames.add(name);
+	}
+	const added = [];
+	for (const entry of entries) {
+		if (existingNames.has(entry.name)) continue;
+		seq.add(doc.createNode({
+			name: entry.name,
+			valueFrom: entry.valueFrom
+		}));
+		added.push(entry.name);
+	}
+	if (added.length > 0) fs.writeFileSync(file, doc.toString());
+	return added;
+}
+/** Navigates/creates a nested map path, returning the leaf map. */
+function ensureMap(doc, pathKeys) {
+	let node = doc.contents;
+	const walked = [];
+	for (const key of pathKeys) {
+		walked.push(key);
+		let child = doc.getIn(walked);
+		if (!child || typeof child.set !== "function") {
+			doc.setIn(walked, doc.createNode({}));
+			child = doc.getIn(walked);
+		}
+		node = child;
+	}
+	return node;
+}
+/**
+* Additively patches `databricks.yml`: adds bundle `variables`, the app
+* `resources` bindings, and the target-level variable values — each only if
+* not already present. Returns the names added plus whether the file changed
+* (a target-value-only write changes the file without adding any names).
+*/
+function patchDatabricksYml(file, plan) {
+	if (plan.bundleVariables.length === 0 && plan.resourceBindings.length === 0) return {
+		added: [],
+		changed: false
+	};
+	const doc = loadDoc(file);
+	const added = [];
+	if (plan.bundleVariables.length > 0) {
+		const vars = ensureMap(doc, ["variables"]);
+		for (const v of plan.bundleVariables) {
+			if (vars.has(v.name)) continue;
+			const body = {};
+			if (v.description) body.description = v.description;
+			vars.set(v.name, doc.createNode(body));
+			added.push(v.name);
+		}
+	}
+	if (plan.resourceBindings.length > 0) {
+		const app = ensureMap(doc, [
+			"resources",
+			"apps",
+			"app"
+		]);
+		let bindings = app.get("resources");
+		if (!bindings || typeof bindings.add !== "function") {
+			app.set("resources", doc.createNode([]));
+			bindings = app.get("resources");
+		}
+		const existing = /* @__PURE__ */ new Set();
+		for (const item of bindings.items) {
+			const name = item?.get?.("name");
+			if (typeof name === "string") existing.add(name);
+		}
+		for (const binding of plan.resourceBindings) {
+			if (existing.has(binding.name)) continue;
+			bindings.add(doc.createNode(bindingToNode(binding)));
+			added.push(binding.name);
+		}
+	}
+	let wroteTargetValue = false;
+	const withValues = plan.bundleVariables.filter((v) => v.value !== void 0);
+	if (withValues.length > 0) {
+		const targetVars = ensureMap(doc, [
+			"targets",
+			"default",
+			"variables"
+		]);
+		for (const v of withValues) {
+			if (targetVars.has(v.name)) continue;
+			targetVars.set(v.name, v.value);
+			wroteTargetValue = true;
+		}
+	}
+	const changed = added.length > 0 || wroteTargetValue;
+	if (changed) fs.writeFileSync(file, doc.toString());
+	return {
+		added,
+		changed
+	};
+}
+/**
+* Applies a config plan to `app.yaml` and `databricks.yml` in `cwd` via
+* comment-preserving additive patches. Never overwrites existing entries.
+*/
+function writeConfig(cwd, plan) {
+	const appAdded = patchAppYaml(path.join(cwd, APP_YAML_FILE), plan.appYamlEnv);
+	const db = patchDatabricksYml(path.join(cwd, DATABRICKS_YML_FILE), plan);
+	return {
+		appYamlChanged: appAdded.length > 0,
+		databricksYmlChanged: db.changed,
+		added: [...new Set([...appAdded, ...db.added])],
+		unverifiedTypes: plan.unverifiedTypes
+	};
+}
+/**
+* Runs `databricks bundle validate` as a post-write correctness gate. Returns
+* true when the config validates (or when the CLI is unavailable — a missing
+* CLI shouldn't fail an install). Surfaces validation errors to the user.
+*/
+function validateBundle(cwd, profile) {
+	const args = ["bundle", "validate"];
+	if (profile) args.push("-p", profile);
+	let result;
+	try {
+		result = spawnSync("databricks", args, {
+			cwd,
+			encoding: "utf-8"
+		});
+	} catch {
+		console.warn(pc.yellow("  Skipped bundle validate (databricks CLI not found)."));
+		return true;
+	}
+	if (result.error) {
+		console.warn(pc.yellow("  Skipped bundle validate (databricks CLI not found)."));
+		return true;
+	}
+	if (result.status !== 0) {
+		console.warn(pc.yellow("  databricks bundle validate reported issues:"));
+		if (result.stderr) console.warn(result.stderr.trim());
+		return false;
+	}
+	return true;
+}
+/** Reports what the config write did, including any unverified-type warnings. */
+function reportConfigWrite(result) {
+	if (result.added.length > 0) console.log(`${pc.green("Updated deploy config:")} ${result.added.join(", ")}`);
+	if (result.unverifiedTypes.length > 0) console.warn(pc.yellow(`  No databricks.yml binding written for: ${result.unverifiedTypes.join(", ")}. Add the resource binding manually before deploy.`));
+}
+
+//#endregion
+export { reportConfigWrite, validateBundle, writeConfig };
+//# sourceMappingURL=config-writer.js.map

package/dist/cli/commands/registry/config-writer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config-writer.js","names":[],"sources":["../../../../src/cli/commands/registry/config-writer.ts"],"sourcesContent":["import { type SpawnSyncReturns, spawnSync } from \"node:child_process\";\nimport fs from \"node:fs\";\nimport path from \"node:path\";\nimport pc from \"picocolors\";\nimport { parseDocument, type YAMLMap, type YAMLSeq } from \"yaml\";\nimport {\n  APP_YAML_FILE,\n  type AppYamlEnvEntry,\n  bindingToNode,\n  DATABRICKS_YML_FILE,\n} from \"../../deploy-config\";\nimport { type ConfigPlan, planHasContent } from \"./config-plan\";\n\nexport interface ConfigWriteResult {\n  appYamlChanged: boolean;\n  databricksYmlChanged: boolean;\n  /** Env/binding names actually added (skipping ones already present). */\n  added: string[];\n  /** Resource types skipped for lack of a verified binding spec. */\n  unverifiedTypes: string[];\n}\n\n/** Reads and parses a YAML file into a Document, or a fresh doc if absent. */\nfunction loadDoc(file: string): ReturnType<typeof parseDocument> {\n  if (fs.existsSync(file)) {\n    return parseDocument(fs.readFileSync(file, \"utf-8\"));\n  }\n  return parseDocument(\"\");\n}\n\n/**\n * Additively patches `app.yaml`'s `env:` list with entries not already present\n * (matched by `name`). Returns the names added.\n */\nfunction patchAppYaml(file: string, entries: AppYamlEnvEntry[]): string[] {\n  if (entries.length === 0) return [];\n  const doc = loadDoc(file);\n  let seq = doc.get(\"env\") as YAMLSeq | undefined;\n  if (!seq || typeof (seq as YAMLSeq).add !== \"function\") {\n    doc.set(\"env\", doc.createNode([]));\n    seq = doc.get(\"env\") as YAMLSeq;\n  }\n\n  const existingNames = new Set<string>();\n  for (const item of seq.items) {\n    const name = (item as YAMLMap)?.get?.(\"name\");\n    if (typeof name === \"string\") existingNames.add(name);\n  }\n\n  const added: string[] = [];\n  for (const entry of entries) {\n    if (existingNames.has(entry.name)) continue;\n    seq.add(doc.createNode({ name: entry.name, valueFrom: entry.valueFrom }));\n    added.push(entry.name);\n  }\n\n  if (added.length > 0) fs.writeFileSync(file, doc.toString());\n  return added;\n}\n\n/** Navigates/creates a nested map path, returning the leaf map. */\nfunction ensureMap(\n  doc: ReturnType<typeof parseDocument>,\n  pathKeys: string[],\n): YAMLMap {\n  let node = doc.contents as unknown as YAMLMap;\n  const walked: string[] = [];\n  for (const key of pathKeys) {\n    walked.push(key);\n    let child = doc.getIn(walked) as YAMLMap | undefined;\n    if (!child || typeof (child as YAMLMap).set !== \"function\") {\n      doc.setIn(walked, doc.createNode({}));\n      child = doc.getIn(walked) as YAMLMap;\n    }\n    node = child;\n  }\n  return node;\n}\n\n/**\n * Additively patches `databricks.yml`: adds bundle `variables`, the app\n * `resources` bindings, and the target-level variable values — each only if\n * not already present. Returns the names added plus whether the file changed\n * (a target-value-only write changes the file without adding any names).\n */\nfunction patchDatabricksYml(\n  file: string,\n  plan: ConfigPlan,\n): { added: string[]; changed: boolean } {\n  if (plan.bundleVariables.length === 0 && plan.resourceBindings.length === 0) {\n    return { added: [], changed: false };\n  }\n  const doc = loadDoc(file);\n  const added: string[] = [];\n\n  // Top-level bundle variables.\n  if (plan.bundleVariables.length > 0) {\n    const vars = ensureMap(doc, [\"variables\"]);\n    for (const v of plan.bundleVariables) {\n      if (vars.has(v.name)) continue;\n      const body: Record<string, string> = {};\n      if (v.description) body.description = v.description;\n      vars.set(v.name, doc.createNode(body));\n      added.push(v.name);\n    }\n  }\n\n  // App resource bindings.\n  if (plan.resourceBindings.length > 0) {\n    const app = ensureMap(doc, [\"resources\", \"apps\", \"app\"]);\n    let bindings = app.get(\"resources\") as YAMLSeq | undefined;\n    if (!bindings || typeof (bindings as YAMLSeq).add !== \"function\") {\n      app.set(\"resources\", doc.createNode([]));\n      bindings = app.get(\"resources\") as YAMLSeq;\n    }\n    const existing = new Set<string>();\n    for (const item of bindings.items) {\n      const name = (item as YAMLMap)?.get?.(\"name\");\n      if (typeof name === \"string\") existing.add(name);\n    }\n    for (const binding of plan.resourceBindings) {\n      if (existing.has(binding.name)) continue;\n      bindings.add(doc.createNode(bindingToNode(binding)));\n      added.push(binding.name);\n    }\n  }\n\n  // Target-level variable values. Tracked separately from `added` because the\n  // binding/top-level var may already exist (e.g. from scaffold) while the\n  // target VALUE is still missing — in that case nothing is in `added` yet the\n  // file still needs writing to persist the assigned value.\n  let wroteTargetValue = false;\n  const withValues = plan.bundleVariables.filter((v) => v.value !== undefined);\n  if (withValues.length > 0) {\n    const targetVars = ensureMap(doc, [\"targets\", \"default\", \"variables\"]);\n    for (const v of withValues) {\n      if (targetVars.has(v.name)) continue;\n      targetVars.set(v.name, v.value);\n      wroteTargetValue = true;\n    }\n  }\n\n  const changed = added.length > 0 || wroteTargetValue;\n  if (changed) fs.writeFileSync(file, doc.toString());\n  return { added, changed };\n}\n\n/**\n * Applies a config plan to `app.yaml` and `databricks.yml` in `cwd` via\n * comment-preserving additive patches. Never overwrites existing entries.\n */\nexport function writeConfig(cwd: string, plan: ConfigPlan): ConfigWriteResult {\n  const appAdded = patchAppYaml(path.join(cwd, APP_YAML_FILE), plan.appYamlEnv);\n  const db = patchDatabricksYml(path.join(cwd, DATABRICKS_YML_FILE), plan);\n  return {\n    appYamlChanged: appAdded.length > 0,\n    databricksYmlChanged: db.changed,\n    added: [...new Set([...appAdded, ...db.added])],\n    unverifiedTypes: plan.unverifiedTypes,\n  };\n}\n\n/**\n * Runs `databricks bundle validate` as a post-write correctness gate. Returns\n * true when the config validates (or when the CLI is unavailable — a missing\n * CLI shouldn't fail an install). Surfaces validation errors to the user.\n */\nexport function validateBundle(cwd: string, profile?: string): boolean {\n  const args = [\"bundle\", \"validate\"];\n  if (profile) args.push(\"-p\", profile);\n  let result: SpawnSyncReturns<string>;\n  try {\n    result = spawnSync(\"databricks\", args, { cwd, encoding: \"utf-8\" });\n  } catch {\n    console.warn(\n      pc.yellow(\"  Skipped bundle validate (databricks CLI not found).\"),\n    );\n    return true;\n  }\n  if (result.error) {\n    console.warn(\n      pc.yellow(\"  Skipped bundle validate (databricks CLI not found).\"),\n    );\n    return true;\n  }\n  if (result.status !== 0) {\n    console.warn(pc.yellow(\"  databricks bundle validate reported issues:\"));\n    if (result.stderr) console.warn(result.stderr.trim());\n    return false;\n  }\n  return true;\n}\n\n/** Reports what the config write did, including any unverified-type warnings. */\nexport function reportConfigWrite(result: ConfigWriteResult): void {\n  if (result.added.length > 0) {\n    console.log(\n      `${pc.green(\"Updated deploy config:\")} ${result.added.join(\", \")}`,\n    );\n  }\n  if (result.unverifiedTypes.length > 0) {\n    console.warn(\n      pc.yellow(\n        `  No databricks.yml binding written for: ${result.unverifiedTypes.join(\", \")}. ` +\n          \"Add the resource binding manually before deploy.\",\n      ),\n    );\n  }\n}\n\nexport { planHasContent };\n"],"mappings":"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"}

package/dist/cli/commands/registry/constants.js

@@ -0,0 +1,62 @@
+import { spawnSync } from "node:child_process";
+
+//#region src/cli/commands/registry/constants.ts
+/** shadcn registry namespace consumers reference, e.g. `@databricks-appkit/metric-card`. */
+const REGISTRY_NAMESPACE = "@databricks-appkit";
+/**
+* A plain JS identifier. A plugin's export name is interpolated into the user's
+* server source, so it's validated against this before use — a registry item is
+* untrusted, and anything else could inject code.
+*/
+const JS_IDENTIFIER = /^[A-Za-z_$][\w$]*$/;
+/** GitHub repo hosting the registry, and the branch the built items live on. */
+const REGISTRY_REPO = "databricks/appkit-registry";
+const REGISTRY_REF = "main";
+/**
+* Public hosting: once the repo is public, items are fetchable directly from
+* raw.githubusercontent.com with no auth.
+*/
+const PUBLIC_RAW_BASE = `https://raw.githubusercontent.com/${REGISTRY_REPO}/${REGISTRY_REF}`;
+const REGISTRY_ITEM_URL_TEMPLATE = `${PUBLIC_RAW_BASE}/public/r/{name}.json`;
+const REGISTRY_INDEX_URL = `${PUBLIC_RAW_BASE}/registry.json`;
+/**
+* Private/internal hosting: while the repo is internal, files are fetched via
+* the GitHub Contents API with a token. `Accept: application/vnd.github.raw`
+* makes the API return the file bytes directly (the registry-item JSON).
+*/
+const GH_CONTENTS_API = `https://api.github.com/repos/${REGISTRY_REPO}/contents`;
+const REGISTRY_ITEM_API_TEMPLATE = `${GH_CONTENTS_API}/public/r/{name}.json?ref=${REGISTRY_REF}`;
+const REGISTRY_INDEX_API_URL = `${GH_CONTENTS_API}/registry.json?ref=${REGISTRY_REF}`;
+/** Env vars checked (in order) for a token granting read access to the repo. */
+const TOKEN_ENV_VARS = [
+	"APPKIT_REGISTRY_TOKEN",
+	"GITHUB_TOKEN",
+	"GH_TOKEN"
+];
+/**
+* Resolves a token granting read access to the registry repo: first the env
+* vars in {@link TOKEN_ENV_VARS}, then the GitHub CLI (`gh auth token`) if the
+* user is logged in. Returns null if none are available.
+*/
+function resolveToken(env = process.env) {
+	for (const envName of TOKEN_ENV_VARS) {
+		const value = env[envName];
+		if (value) return {
+			envName,
+			value
+		};
+	}
+	try {
+		const res = spawnSync("gh", ["auth", "token"], { encoding: "utf-8" });
+		const value = res.status === 0 ? res.stdout.trim() : "";
+		if (value) return {
+			envName: "gh auth token",
+			value
+		};
+	} catch {}
+	return null;
+}
+
+//#endregion
+export { JS_IDENTIFIER, REGISTRY_INDEX_API_URL, REGISTRY_INDEX_URL, REGISTRY_ITEM_API_TEMPLATE, REGISTRY_ITEM_URL_TEMPLATE, REGISTRY_NAMESPACE, REGISTRY_REPO, resolveToken };
+//# sourceMappingURL=constants.js.map

package/dist/cli/commands/registry/constants.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.js","names":[],"sources":["../../../../src/cli/commands/registry/constants.ts"],"sourcesContent":["import { spawnSync } from \"node:child_process\";\n\n/** shadcn registry namespace consumers reference, e.g. `@databricks-appkit/metric-card`. */\nexport const REGISTRY_NAMESPACE = \"@databricks-appkit\";\n\n/**\n * A plain JS identifier. A plugin's export name is interpolated into the user's\n * server source, so it's validated against this before use — a registry item is\n * untrusted, and anything else could inject code.\n */\nexport const JS_IDENTIFIER = /^[A-Za-z_$][\\w$]*$/;\n\n/** GitHub repo hosting the registry, and the branch the built items live on. */\nexport const REGISTRY_REPO = \"databricks/appkit-registry\";\nexport const REGISTRY_REF = \"main\";\n\n/**\n * Public hosting: once the repo is public, items are fetchable directly from\n * raw.githubusercontent.com with no auth.\n */\nconst PUBLIC_RAW_BASE = `https://raw.githubusercontent.com/${REGISTRY_REPO}/${REGISTRY_REF}`;\nexport const REGISTRY_ITEM_URL_TEMPLATE = `${PUBLIC_RAW_BASE}/public/r/{name}.json`;\nexport const REGISTRY_INDEX_URL = `${PUBLIC_RAW_BASE}/registry.json`;\n\n/**\n * Private/internal hosting: while the repo is internal, files are fetched via\n * the GitHub Contents API with a token. `Accept: application/vnd.github.raw`\n * makes the API return the file bytes directly (the registry-item JSON).\n */\nconst GH_CONTENTS_API = `https://api.github.com/repos/${REGISTRY_REPO}/contents`;\nexport const REGISTRY_ITEM_API_TEMPLATE = `${GH_CONTENTS_API}/public/r/{name}.json?ref=${REGISTRY_REF}`;\nexport const REGISTRY_INDEX_API_URL = `${GH_CONTENTS_API}/registry.json?ref=${REGISTRY_REF}`;\n\n/** Env vars checked (in order) for a token granting read access to the repo. */\nexport const TOKEN_ENV_VARS = [\n  \"APPKIT_REGISTRY_TOKEN\",\n  \"GITHUB_TOKEN\",\n  \"GH_TOKEN\",\n];\n\nexport interface RegistryToken {\n  envName: string;\n  value: string;\n}\n\n/**\n * Resolves a token granting read access to the registry repo: first the env\n * vars in {@link TOKEN_ENV_VARS}, then the GitHub CLI (`gh auth token`) if the\n * user is logged in. Returns null if none are available.\n */\nexport function resolveToken(\n  env: NodeJS.ProcessEnv = process.env,\n): RegistryToken | null {\n  for (const envName of TOKEN_ENV_VARS) {\n    const value = env[envName];\n    if (value) return { envName, value };\n  }\n  try {\n    const res = spawnSync(\"gh\", [\"auth\", \"token\"], { encoding: \"utf-8\" });\n    const value = res.status === 0 ? res.stdout.trim() : \"\";\n    if (value) return { envName: \"gh auth token\", value };\n  } catch {\n    // gh not installed or not on PATH — fall through.\n  }\n  return null;\n}\n"],"mappings":";;;;AAGA,MAAa,qBAAqB;;;;;;AAOlC,MAAa,gBAAgB;;AAG7B,MAAa,gBAAgB;AAC7B,MAAa,eAAe;;;;;AAM5B,MAAM,kBAAkB,qCAAqC,cAAc,GAAG;AAC9E,MAAa,6BAA6B,GAAG,gBAAgB;AAC7D,MAAa,qBAAqB,GAAG,gBAAgB;;;;;;AAOrD,MAAM,kBAAkB,gCAAgC,cAAc;AACtE,MAAa,6BAA6B,GAAG,gBAAgB,4BAA4B;AACzF,MAAa,yBAAyB,GAAG,gBAAgB,qBAAqB;;AAG9E,MAAa,iBAAiB;CAC5B;CACA;CACA;CACD;;;;;;AAYD,SAAgB,aACd,MAAyB,QAAQ,KACX;AACtB,MAAK,MAAM,WAAW,gBAAgB;EACpC,MAAM,QAAQ,IAAI;AAClB,MAAI,MAAO,QAAO;GAAE;GAAS;GAAO;;AAEtC,KAAI;EACF,MAAM,MAAM,UAAU,MAAM,CAAC,QAAQ,QAAQ,EAAE,EAAE,UAAU,SAAS,CAAC;EACrE,MAAM,QAAQ,IAAI,WAAW,IAAI,IAAI,OAAO,MAAM,GAAG;AACrD,MAAI,MAAO,QAAO;GAAE,SAAS;GAAiB;GAAO;SAC/C;AAGR,QAAO"}

package/dist/cli/commands/registry/env-reconcile.js

@@ -0,0 +1,116 @@
+import { fieldOrigin, isValidEnvName } from "./requirements.js";
+import dotenv from "dotenv";
+
+//#region src/cli/commands/registry/env-reconcile.ts
+/**
+* A `.env` value is a single line: `KEY=VALUE`. A value carrying a CR/LF would
+* write extra lines when serialized, so a malicious static default like
+* `value: "y\nDATABRICKS_HOST=attacker"` could inject an unrelated key (host
+* override → credential exfil). Registry manifests are untrusted, so any value
+* with a line break is rejected rather than written.
+*/
+function isSafeEnvValue(value) {
+	return !/[\r\n]/.test(value);
+}
+/**
+* Flattens requirement rows into the env vars that belong in local `.env`.
+* Excludes fields with no `env` name and `platform`-origin fields (deploy-time
+* platform injection). Order: required resources first (as given), then optional.
+*/
+function collectEnvNeeds(rows) {
+	const needs = [];
+	const seen = /* @__PURE__ */ new Set();
+	const ordered = [...rows.filter((r) => r.required), ...rows.filter((r) => !r.required)];
+	for (const row of ordered) for (const field of row.fields) {
+		if (!includeInEnv(field)) continue;
+		const env = field.env;
+		if (seen.has(env)) continue;
+		seen.add(env);
+		needs.push({
+			env,
+			resourceType: row.type,
+			required: row.required,
+			defaultValue: field.value,
+			origin: fieldOrigin(field),
+			description: field.description
+		});
+	}
+	return needs;
+}
+/** A field belongs in `.env` iff it names a valid env var and isn't platform-injected. */
+function includeInEnv(field) {
+	if (!field.env) return false;
+	if (!isValidEnvName(field.env)) return false;
+	return fieldOrigin(field) !== "platform";
+}
+/**
+* Parses a `.env` file body into a KEY -> value map, using the same `dotenv`
+* parser the app loads `.env` with at runtime so the CLI reads it identically.
+*/
+function parseEnv(content) {
+	return dotenv.parse(content);
+}
+/**
+* Serializes new env entries for appending to a `.env` file. Only keys not
+* already present are emitted; existing keys are never rewritten (we don't
+* clobber user edits). Returns the text to append (empty if nothing new).
+*/
+function serializeEnvAppend(entries) {
+	if (entries.length === 0) return "";
+	const lines = [];
+	for (const e of entries) {
+		if (e.comment) lines.push(`# ${e.comment}`);
+		lines.push(`${e.env}=${e.value}`);
+	}
+	return `${lines.join("\n")}\n`;
+}
+/**
+* Reconciles the needed env vars against what's already in `.env`.
+* - Already-set keys are reported as "already-set" and never overwritten.
+* - static-origin defaults are used without invoking `provide`.
+* - Everything else defers to `provide`; a returned undefined means skip.
+*/
+async function reconcileEnv(needs, opts) {
+	const resolutions = [];
+	for (const need of needs) {
+		const current = opts.existing[need.env];
+		if (current !== void 0 && current !== "") {
+			resolutions.push({
+				env: need.env,
+				value: current,
+				status: "already-set"
+			});
+			continue;
+		}
+		if (need.defaultValue !== void 0) {
+			if (!isSafeEnvValue(need.defaultValue)) {
+				resolutions.push({
+					env: need.env,
+					status: "skipped"
+				});
+				continue;
+			}
+			resolutions.push({
+				env: need.env,
+				value: need.defaultValue,
+				status: "written"
+			});
+			continue;
+		}
+		const value = await opts.provide(need);
+		if (value === void 0 || value === "" || !isSafeEnvValue(value)) resolutions.push({
+			env: need.env,
+			status: "skipped"
+		});
+		else resolutions.push({
+			env: need.env,
+			value,
+			status: "written"
+		});
+	}
+	return resolutions;
+}
+
+//#endregion
+export { collectEnvNeeds, parseEnv, reconcileEnv, serializeEnvAppend };
+//# sourceMappingURL=env-reconcile.js.map

package/dist/cli/commands/registry/env-reconcile.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"env-reconcile.js","names":[],"sources":["../../../../src/cli/commands/registry/env-reconcile.ts"],"sourcesContent":["import dotenv from \"dotenv\";\nimport {\n  fieldOrigin,\n  isValidEnvName,\n  type RequirementField,\n  type ResourceRequirementRow,\n} from \"./requirements\";\n\n/**\n * A single env var that an installed plugin needs in the local `.env`.\n * `platform`-origin fields are excluded upstream — they are injected by\n * Databricks Apps at deploy time and never belong in a hand-managed `.env`.\n */\nexport interface EnvNeed {\n  env: string;\n  resourceType: string;\n  required: boolean;\n  /** static-origin default value, pre-filled without prompting. */\n  defaultValue?: string;\n  origin?: string;\n  description?: string;\n}\n\n/** The resolved decision for one env var after reconciliation. */\nexport interface EnvResolution {\n  env: string;\n  /** The value to write, or undefined when skipped / left unset. */\n  value?: string;\n  status: \"written\" | \"already-set\" | \"skipped\";\n}\n\n/**\n * A `.env` value is a single line: `KEY=VALUE`. A value carrying a CR/LF would\n * write extra lines when serialized, so a malicious static default like\n * `value: \"y\\nDATABRICKS_HOST=attacker\"` could inject an unrelated key (host\n * override → credential exfil). Registry manifests are untrusted, so any value\n * with a line break is rejected rather than written.\n */\nexport function isSafeEnvValue(value: string): boolean {\n  return !/[\\r\\n]/.test(value);\n}\n\n/**\n * Flattens requirement rows into the env vars that belong in local `.env`.\n * Excludes fields with no `env` name and `platform`-origin fields (deploy-time\n * platform injection). Order: required resources first (as given), then optional.\n */\nexport function collectEnvNeeds(rows: ResourceRequirementRow[]): EnvNeed[] {\n  const needs: EnvNeed[] = [];\n  const seen = new Set<string>();\n  const ordered = [\n    ...rows.filter((r) => r.required),\n    ...rows.filter((r) => !r.required),\n  ];\n  for (const row of ordered) {\n    for (const field of row.fields) {\n      if (!includeInEnv(field)) continue;\n      const env = field.env as string;\n      if (seen.has(env)) continue;\n      seen.add(env);\n      needs.push({\n        env,\n        resourceType: row.type,\n        required: row.required,\n        defaultValue: field.value,\n        origin: fieldOrigin(field),\n        description: field.description,\n      });\n    }\n  }\n  return needs;\n}\n\n/** A field belongs in `.env` iff it names a valid env var and isn't platform-injected. */\nfunction includeInEnv(field: RequirementField): boolean {\n  if (!field.env) return false;\n  // The env name comes from an untrusted manifest and is written as `NAME=value`;\n  // a malformed name (e.g. one containing a newline) could inject an extra .env\n  // line, so drop anything that isn't a plain env identifier.\n  if (!isValidEnvName(field.env)) return false;\n  // Origin is derived from the authored contract (localOnly/value/resolve) so\n  // registry-fetched manifests without a computed origin classify correctly.\n  return fieldOrigin(field) !== \"platform\";\n}\n\n/**\n * Parses a `.env` file body into a KEY -> value map, using the same `dotenv`\n * parser the app loads `.env` with at runtime so the CLI reads it identically.\n */\nexport function parseEnv(content: string): Record<string, string> {\n  return dotenv.parse(content);\n}\n\n/**\n * Serializes new env entries for appending to a `.env` file. Only keys not\n * already present are emitted; existing keys are never rewritten (we don't\n * clobber user edits). Returns the text to append (empty if nothing new).\n */\nexport function serializeEnvAppend(\n  entries: Array<{ env: string; value: string; comment?: string }>,\n): string {\n  if (entries.length === 0) return \"\";\n  const lines: string[] = [];\n  for (const e of entries) {\n    if (e.comment) lines.push(`# ${e.comment}`);\n    lines.push(`${e.env}=${e.value}`);\n  }\n  return `${lines.join(\"\\n\")}\\n`;\n}\n\n/** Provides a value for an env need, or undefined to skip it. */\nexport type ValueProvider = (need: EnvNeed) => Promise<string | undefined>;\n\nexport interface ReconcileOptions {\n  /** Existing parsed `.env` values (keys already present are left untouched). */\n  existing: Record<string, string>;\n  /** Resolves a value for each unset need (prompt in interactive, flag in CI). */\n  provide: ValueProvider;\n}\n\n/**\n * Reconciles the needed env vars against what's already in `.env`.\n * - Already-set keys are reported as \"already-set\" and never overwritten.\n * - static-origin defaults are used without invoking `provide`.\n * - Everything else defers to `provide`; a returned undefined means skip.\n */\nexport async function reconcileEnv(\n  needs: EnvNeed[],\n  opts: ReconcileOptions,\n): Promise<EnvResolution[]> {\n  const resolutions: EnvResolution[] = [];\n  for (const need of needs) {\n    const current = opts.existing[need.env];\n    if (current !== undefined && current !== \"\") {\n      // Carry the existing value so callers can still feed it into deploy\n      // config (databricks.yml target variables) — the var is set in .env but\n      // its bundle binding still needs the value assigned.\n      resolutions.push({\n        env: need.env,\n        value: current,\n        status: \"already-set\",\n      });\n      continue;\n    }\n    if (need.defaultValue !== undefined) {\n      // Static default from an untrusted manifest — refuse a value that would\n      // inject extra `.env` lines rather than silently writing it.\n      if (!isSafeEnvValue(need.defaultValue)) {\n        resolutions.push({ env: need.env, status: \"skipped\" });\n        continue;\n      }\n      resolutions.push({\n        env: need.env,\n        value: need.defaultValue,\n        status: \"written\",\n      });\n      continue;\n    }\n    const value = await opts.provide(need);\n    if (value === undefined || value === \"\" || !isSafeEnvValue(value)) {\n      resolutions.push({ env: need.env, status: \"skipped\" });\n    } else {\n      resolutions.push({ env: need.env, value, status: \"written\" });\n    }\n  }\n  return resolutions;\n}\n"],"mappings":";;;;;;;;;;;AAsCA,SAAgB,eAAe,OAAwB;AACrD,QAAO,CAAC,SAAS,KAAK,MAAM;;;;;;;AAQ9B,SAAgB,gBAAgB,MAA2C;CACzE,MAAM,QAAmB,EAAE;CAC3B,MAAM,uBAAO,IAAI,KAAa;CAC9B,MAAM,UAAU,CACd,GAAG,KAAK,QAAQ,MAAM,EAAE,SAAS,EACjC,GAAG,KAAK,QAAQ,MAAM,CAAC,EAAE,SAAS,CACnC;AACD,MAAK,MAAM,OAAO,QAChB,MAAK,MAAM,SAAS,IAAI,QAAQ;AAC9B,MAAI,CAAC,aAAa,MAAM,CAAE;EAC1B,MAAM,MAAM,MAAM;AAClB,MAAI,KAAK,IAAI,IAAI,CAAE;AACnB,OAAK,IAAI,IAAI;AACb,QAAM,KAAK;GACT;GACA,cAAc,IAAI;GAClB,UAAU,IAAI;GACd,cAAc,MAAM;GACpB,QAAQ,YAAY,MAAM;GAC1B,aAAa,MAAM;GACpB,CAAC;;AAGN,QAAO;;;AAIT,SAAS,aAAa,OAAkC;AACtD,KAAI,CAAC,MAAM,IAAK,QAAO;AAIvB,KAAI,CAAC,eAAe,MAAM,IAAI,CAAE,QAAO;AAGvC,QAAO,YAAY,MAAM,KAAK;;;;;;AAOhC,SAAgB,SAAS,SAAyC;AAChE,QAAO,OAAO,MAAM,QAAQ;;;;;;;AAQ9B,SAAgB,mBACd,SACQ;AACR,KAAI,QAAQ,WAAW,EAAG,QAAO;CACjC,MAAM,QAAkB,EAAE;AAC1B,MAAK,MAAM,KAAK,SAAS;AACvB,MAAI,EAAE,QAAS,OAAM,KAAK,KAAK,EAAE,UAAU;AAC3C,QAAM,KAAK,GAAG,EAAE,IAAI,GAAG,EAAE,QAAQ;;AAEnC,QAAO,GAAG,MAAM,KAAK,KAAK,CAAC;;;;;;;;AAmB7B,eAAsB,aACpB,OACA,MAC0B;CAC1B,MAAM,cAA+B,EAAE;AACvC,MAAK,MAAM,QAAQ,OAAO;EACxB,MAAM,UAAU,KAAK,SAAS,KAAK;AACnC,MAAI,YAAY,UAAa,YAAY,IAAI;AAI3C,eAAY,KAAK;IACf,KAAK,KAAK;IACV,OAAO;IACP,QAAQ;IACT,CAAC;AACF;;AAEF,MAAI,KAAK,iBAAiB,QAAW;AAGnC,OAAI,CAAC,eAAe,KAAK,aAAa,EAAE;AACtC,gBAAY,KAAK;KAAE,KAAK,KAAK;KAAK,QAAQ;KAAW,CAAC;AACtD;;AAEF,eAAY,KAAK;IACf,KAAK,KAAK;IACV,OAAO,KAAK;IACZ,QAAQ;IACT,CAAC;AACF;;EAEF,MAAM,QAAQ,MAAM,KAAK,QAAQ,KAAK;AACtC,MAAI,UAAU,UAAa,UAAU,MAAM,CAAC,eAAe,MAAM,CAC/D,aAAY,KAAK;GAAE,KAAK,KAAK;GAAK,QAAQ;GAAW,CAAC;MAEtD,aAAY,KAAK;GAAE,KAAK,KAAK;GAAK;GAAO,QAAQ;GAAW,CAAC;;AAGjE,QAAO"}