@databricks/appkit-ui 0.59.0 → 0.61.0

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"}

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

@@ -0,0 +1,198 @@
+import { collectEnvNeeds, parseEnv, reconcileEnv, serializeEnvAppend } from "./env-reconcile.js";
+import { composeResourceId, isFlatListable, isParentContext, listParentContextStep, listWorkspaceResources, parentContextDepth } from "./workspace-picker.js";
+import fs from "node:fs";
+import path from "node:path";
+import pc from "picocolors";
+import { autocomplete, isCancel, select, text } from "@clack/prompts";
+
+//#region src/cli/commands/registry/env-writer.ts
+/** Sentinel select value meaning "let me type the id myself". */
+const MANUAL = "__manual__";
+/**
+* Max resources shown in a picker select. Real workspaces can have thousands
+* (e.g. 5000+ SQL warehouses); an unbounded select is unusable. Beyond this we
+* show the first N and log how many were hidden — never silently drop — and the
+* "Enter manually" option always lets the user type an id the list omits.
+*/
+const PICKER_LIMIT = 25;
+/** Reads a `.env`-style file into a map; empty when the file is absent. */
+function readEnvFile(file) {
+	if (!fs.existsSync(file)) return {};
+	return parseEnv(fs.readFileSync(file, "utf-8"));
+}
+/** Appends text to a file, creating it (with a trailing newline) if needed. */
+function appendToFile(file, text) {
+	if (text === "") return;
+	if (fs.existsSync(file)) {
+		const existing = fs.readFileSync(file, "utf-8");
+		const sep = existing.length > 0 && !existing.endsWith("\n") ? "\n" : "";
+		fs.writeFileSync(file, existing + sep + text);
+	} else fs.writeFileSync(file, text);
+}
+/**
+* Caps a choice list to {@link PICKER_LIMIT} for display, logging how many were
+* hidden so the truncation is never silent. The caller always appends an
+* "Enter manually" option, so an omitted resource is still reachable.
+*/
+function capChoices(choices, resourceType, limit = PICKER_LIMIT) {
+	if (choices.length <= limit) return choices;
+	console.log(pc.dim(`  ${choices.length} ${resourceType}s found; showing first ${limit}. Use "Enter manually" if yours is not listed.`));
+	return choices.slice(0, limit);
+}
+/** Free-text prompt for one env need; undefined to skip. */
+async function promptText(need) {
+	const tag = need.required ? "required" : "optional";
+	const answer = await text({
+		message: `${need.env} (${need.resourceType}, ${tag})`,
+		placeholder: need.description ?? "leave blank to skip"
+	});
+	if (isCancel(answer)) return void 0;
+	const value = (answer ?? "").trim();
+	return value === "" ? void 0 : value;
+}
+/** Presents one workspace list as a select; MANUAL/cancel handled by caller. */
+async function selectFrom(message, choices) {
+	const picked = await select({
+		message,
+		options: [...choices, {
+			value: MANUAL,
+			label: "Enter manually / skip"
+		}]
+	});
+	if (isCancel(picked)) return null;
+	return String(picked);
+}
+/**
+* Type-to-filter picker over the full choice list (no cap): the user searches
+* by name/id as they type. Appends "Enter manually" so an omitted value is
+* still reachable. Returns MANUAL to fall through to free-text, or null on
+* cancel.
+*/
+async function autocompleteFrom(message, choices) {
+	const picked = await autocomplete({
+		message,
+		options: [...choices, {
+			value: MANUAL,
+			label: "Enter manually / skip"
+		}],
+		placeholder: "type to search…"
+	});
+	if (isCancel(picked)) return null;
+	return String(picked);
+}
+/**
+* Drill-down picker for parent-context types (volume→catalog/schema,
+* secret→scope, vector_search_index→endpoint). Walks each step, listing the
+* next level from the prior pick. Returns the final resource id, or undefined
+* to fall back to free-text (on cancel, empty level, or MANUAL at any step).
+*/
+async function pickParentContext(need, profile) {
+	const depth = parentContextDepth(need.resourceType);
+	const picks = [];
+	for (let i = 0; i < depth; i++) {
+		const step = listParentContextStep(need.resourceType, i, picks, profile);
+		if (!step || step.choices.length === 0) {
+			console.log(pc.dim(`  No ${step?.key ?? need.resourceType} found — enter the id manually.`));
+			return;
+		}
+		const picked = await selectFrom(`${need.env} — pick a ${step.key}`, capChoices(step.choices, step.key));
+		if (picked === null || picked === MANUAL) return void 0;
+		picks.push(picked);
+	}
+	return composeResourceId(need.resourceType, picks);
+}
+/**
+* Builds the value provider. Precedence: --env flag, then (interactive only) a
+* workspace picker — flat select for flat-listable types, drill-down for
+* parent-context types — else a free-text prompt. The picker degrades to
+* free-text whenever the workspace can't be listed (no profile, offline, auth
+* error, empty) so it never hard-fails.
+*/
+function makeProvider(opts) {
+	return async (need) => {
+		const fromFlag = opts.values?.[need.env];
+		if (fromFlag !== void 0) return fromFlag;
+		if (opts.nonInteractive) return void 0;
+		if (isFlatListable(need.resourceType)) {
+			const { choices, truncated, error } = await listWorkspaceResources(need.resourceType, opts.profile);
+			if (choices.length > 0) {
+				if (truncated) console.log(pc.dim(`  Showing the first ${choices.length} ${need.resourceType}s; use "Enter manually" if yours isn't listed.`));
+				const picked = await autocompleteFrom(`${need.env} — search ${need.resourceType}s`, choices);
+				if (picked === null) return void 0;
+				if (picked !== MANUAL) return picked;
+			} else if (error) {
+				console.log(pc.yellow(`  Couldn't list ${need.resourceType}s from the workspace (${error}).`));
+				console.log(pc.dim("  Enter an id manually, or re-run with --profile <name> (or set DATABRICKS_CONFIG_PROFILE) so the picker can reach the workspace."));
+			} else console.log(pc.dim(`  No ${need.resourceType} found in the workspace — enter an id manually.`));
+		} else if (isParentContext(need.resourceType)) {
+			const picked = await pickParentContext(need, opts.profile);
+			if (picked !== void 0) return picked;
+		}
+		return promptText(need);
+	};
+}
+/**
+* Reconciles a plugin's declared resource env vars into the app's local `.env`
+* (and mirrors variable names into `.env.example`). Never overwrites keys the
+* user already set; skips platform-injected fields. Returns the per-var
+* resolutions so callers can report what happened.
+*/
+async function syncEnv(rows, opts) {
+	const needs = collectEnvNeeds(rows);
+	if (needs.length === 0) return [];
+	const envPath = path.join(opts.cwd, ".env");
+	const examplePath = path.join(opts.cwd, ".env.example");
+	const resolutions = await reconcileEnv(needs, {
+		existing: readEnvFile(envPath),
+		provide: makeProvider(opts)
+	});
+	appendToFile(envPath, serializeEnvAppend(resolutions.filter((r) => r.status === "written" && r.value !== void 0).map((r) => ({
+		env: r.env,
+		value: r.value
+	}))));
+	const exampleExisting = readEnvFile(examplePath);
+	appendToFile(examplePath, serializeEnvAppend(needs.filter((n) => !(n.env in exampleExisting)).map((n) => ({
+		env: n.env,
+		value: ""
+	}))));
+	return resolutions;
+}
+/**
+* Prompts for the {@link BindingValueNeed}s that `.env` reconciliation can't
+* collect, returning a `fieldKey -> value` map for buildConfigPlan. Values are
+* not written to `.env` (these fields have no env var). Non-interactive mode
+* uses `values[fieldKey]` if provided, else leaves the field unset.
+*/
+async function collectBindingValues(needs, opts) {
+	const out = {};
+	for (const need of needs) {
+		const fromFlag = opts.values?.[need.fieldKey];
+		if (fromFlag !== void 0) {
+			out[need.fieldKey] = fromFlag;
+			continue;
+		}
+		if (opts.nonInteractive) continue;
+		const answer = await text({
+			message: `${need.fieldKey} (${need.resourceType}) — required for databricks.yml`,
+			placeholder: need.description ?? "leave blank to set before deploy"
+		});
+		if (isCancel(answer)) continue;
+		const value = (answer ?? "").trim();
+		if (value !== "") out[need.fieldKey] = value;
+	}
+	return out;
+}
+/** Prints a concise summary of what env reconciliation did. */
+function reportEnvResolutions(resolutions) {
+	if (resolutions.length === 0) return;
+	const written = resolutions.filter((r) => r.status === "written");
+	const already = resolutions.filter((r) => r.status === "already-set");
+	const skipped = resolutions.filter((r) => r.status === "skipped");
+	if (written.length > 0) console.log(`${pc.green("Wrote to .env:")} ${written.map((r) => r.env).join(", ")}`);
+	if (already.length > 0) console.log(pc.dim(`Already set: ${already.map((r) => r.env).join(", ")}`));
+	if (skipped.length > 0) console.log(`${pc.yellow("Left unset (set before deploy):")} ${skipped.map((r) => r.env).join(", ")}`);
+}
+
+//#endregion
+export { collectBindingValues, reportEnvResolutions, syncEnv };
+//# sourceMappingURL=env-writer.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"env-writer.js","names":[],"sources":["../../../../src/cli/commands/registry/env-writer.ts"],"sourcesContent":["import fs from \"node:fs\";\nimport path from \"node:path\";\nimport { autocomplete, isCancel, select, text } from \"@clack/prompts\";\nimport pc from \"picocolors\";\nimport type { BindingValueNeed } from \"./config-plan\";\nimport {\n  collectEnvNeeds,\n  type EnvNeed,\n  type EnvResolution,\n  parseEnv,\n  reconcileEnv,\n  serializeEnvAppend,\n  type ValueProvider,\n} from \"./env-reconcile\";\nimport type { ResourceRequirementRow } from \"./requirements\";\nimport {\n  composeResourceId,\n  isFlatListable,\n  isParentContext,\n  listParentContextStep,\n  listWorkspaceResources,\n  parentContextDepth,\n} from \"./workspace-picker\";\n\nexport interface EnvSyncOptions {\n  /** Directory holding `.env` / `.env.example` (the app root). */\n  cwd: string;\n  /** true = never prompt (agent/CI). Uses flag values or leaves unset. */\n  nonInteractive: boolean;\n  /** Pre-supplied env values from flags, e.g. { DATABRICKS_WAREHOUSE_ID: \"abc\" }. */\n  values?: Record<string, string>;\n  /** Databricks profile for the workspace picker (else the CLI default). */\n  profile?: string;\n}\n\n/** Sentinel select value meaning \"let me type the id myself\". */\nconst MANUAL = \"__manual__\";\n\n/**\n * Max resources shown in a picker select. Real workspaces can have thousands\n * (e.g. 5000+ SQL warehouses); an unbounded select is unusable. Beyond this we\n * show the first N and log how many were hidden — never silently drop — and the\n * \"Enter manually\" option always lets the user type an id the list omits.\n */\nconst PICKER_LIMIT = 25;\n\n/** Reads a `.env`-style file into a map; empty when the file is absent. */\nfunction readEnvFile(file: string): Record<string, string> {\n  if (!fs.existsSync(file)) return {};\n  return parseEnv(fs.readFileSync(file, \"utf-8\"));\n}\n\n/** Appends text to a file, creating it (with a trailing newline) if needed. */\nfunction appendToFile(file: string, text: string): void {\n  if (text === \"\") return;\n  if (fs.existsSync(file)) {\n    const existing = fs.readFileSync(file, \"utf-8\");\n    const sep = existing.length > 0 && !existing.endsWith(\"\\n\") ? \"\\n\" : \"\";\n    fs.writeFileSync(file, existing + sep + text);\n  } else {\n    fs.writeFileSync(file, text);\n  }\n}\n\n/**\n * Caps a choice list to {@link PICKER_LIMIT} for display, logging how many were\n * hidden so the truncation is never silent. The caller always appends an\n * \"Enter manually\" option, so an omitted resource is still reachable.\n */\nexport function capChoices<T>(\n  choices: T[],\n  resourceType: string,\n  limit = PICKER_LIMIT,\n): T[] {\n  if (choices.length <= limit) return choices;\n  console.log(\n    pc.dim(\n      `  ${choices.length} ${resourceType}s found; showing first ${limit}. ` +\n        'Use \"Enter manually\" if yours is not listed.',\n    ),\n  );\n  return choices.slice(0, limit);\n}\n\n/** Free-text prompt for one env need; undefined to skip. */\nasync function promptText(need: EnvNeed): Promise<string | undefined> {\n  const tag = need.required ? \"required\" : \"optional\";\n  const answer = await text({\n    message: `${need.env} (${need.resourceType}, ${tag})`,\n    placeholder: need.description ?? \"leave blank to skip\",\n  });\n  if (isCancel(answer)) return undefined;\n  const value = (answer ?? \"\").trim();\n  return value === \"\" ? undefined : value;\n}\n\n/** Presents one workspace list as a select; MANUAL/cancel handled by caller. */\nasync function selectFrom(\n  message: string,\n  choices: { value: string; label: string }[],\n): Promise<string | typeof MANUAL | null> {\n  const picked = await select({\n    message,\n    options: [...choices, { value: MANUAL, label: \"Enter manually / skip\" }],\n  });\n  if (isCancel(picked)) return null;\n  return String(picked) as string | typeof MANUAL;\n}\n\n/**\n * Type-to-filter picker over the full choice list (no cap): the user searches\n * by name/id as they type. Appends \"Enter manually\" so an omitted value is\n * still reachable. Returns MANUAL to fall through to free-text, or null on\n * cancel.\n */\nasync function autocompleteFrom(\n  message: string,\n  choices: { value: string; label: string }[],\n): Promise<string | typeof MANUAL | null> {\n  const picked = await autocomplete({\n    message,\n    options: [...choices, { value: MANUAL, label: \"Enter manually / skip\" }],\n    placeholder: \"type to search…\",\n  });\n  if (isCancel(picked)) return null;\n  return String(picked) as string | typeof MANUAL;\n}\n\n/**\n * Drill-down picker for parent-context types (volume→catalog/schema,\n * secret→scope, vector_search_index→endpoint). Walks each step, listing the\n * next level from the prior pick. Returns the final resource id, or undefined\n * to fall back to free-text (on cancel, empty level, or MANUAL at any step).\n */\nasync function pickParentContext(\n  need: EnvNeed,\n  profile: string | undefined,\n): Promise<string | undefined> {\n  const depth = parentContextDepth(need.resourceType);\n  const picks: string[] = [];\n  for (let i = 0; i < depth; i++) {\n    const step = listParentContextStep(need.resourceType, i, picks, profile);\n    if (!step || step.choices.length === 0) {\n      console.log(\n        pc.dim(\n          `  No ${step?.key ?? need.resourceType} found — enter the id manually.`,\n        ),\n      );\n      return undefined;\n    }\n    const picked = await selectFrom(\n      `${need.env} — pick a ${step.key}`,\n      capChoices(step.choices, step.key),\n    );\n    if (picked === null || picked === MANUAL) return undefined;\n    picks.push(picked);\n  }\n  // Compose the id from the picks: most types end on a self-qualified id, but a\n  // secret needs both scope and key (scope/key).\n  return composeResourceId(need.resourceType, picks);\n}\n\n/**\n * Builds the value provider. Precedence: --env flag, then (interactive only) a\n * workspace picker — flat select for flat-listable types, drill-down for\n * parent-context types — else a free-text prompt. The picker degrades to\n * free-text whenever the workspace can't be listed (no profile, offline, auth\n * error, empty) so it never hard-fails.\n */\nfunction makeProvider(opts: EnvSyncOptions): ValueProvider {\n  return async (need: EnvNeed) => {\n    const fromFlag = opts.values?.[need.env];\n    if (fromFlag !== undefined) return fromFlag;\n    if (opts.nonInteractive) return undefined;\n\n    if (isFlatListable(need.resourceType)) {\n      const { choices, truncated, error } = await listWorkspaceResources(\n        need.resourceType,\n        opts.profile,\n      );\n      if (choices.length > 0) {\n        if (truncated) {\n          console.log(\n            pc.dim(\n              `  Showing the first ${choices.length} ${need.resourceType}s; use \"Enter manually\" if yours isn't listed.`,\n            ),\n          );\n        }\n        const picked = await autocompleteFrom(\n          `${need.env} — search ${need.resourceType}s`,\n          choices,\n        );\n        if (picked === null) return undefined;\n        if (picked !== MANUAL) return picked;\n        // fall through to free-text\n      } else if (error) {\n        // Listing failed (usually auth/profile) — say so, don't pretend the\n        // workspace is empty, and point at the fix.\n        console.log(\n          pc.yellow(\n            `  Couldn't list ${need.resourceType}s from the workspace (${error}).`,\n          ),\n        );\n        console.log(\n          pc.dim(\n            \"  Enter an id manually, or re-run with --profile <name> (or set DATABRICKS_CONFIG_PROFILE) so the picker can reach the workspace.\",\n          ),\n        );\n      } else {\n        console.log(\n          pc.dim(\n            `  No ${need.resourceType} found in the workspace — enter an id manually.`,\n          ),\n        );\n      }\n    } else if (isParentContext(need.resourceType)) {\n      const picked = await pickParentContext(need, opts.profile);\n      if (picked !== undefined) return picked;\n      // fall through to free-text\n    }\n\n    return promptText(need);\n  };\n}\n\n/**\n * Reconciles a plugin's declared resource env vars into the app's local `.env`\n * (and mirrors variable names into `.env.example`). Never overwrites keys the\n * user already set; skips platform-injected fields. Returns the per-var\n * resolutions so callers can report what happened.\n */\nexport async function syncEnv(\n  rows: ResourceRequirementRow[],\n  opts: EnvSyncOptions,\n): Promise<EnvResolution[]> {\n  const needs = collectEnvNeeds(rows);\n  if (needs.length === 0) return [];\n\n  const envPath = path.join(opts.cwd, \".env\");\n  const examplePath = path.join(opts.cwd, \".env.example\");\n  const existing = readEnvFile(envPath);\n\n  const resolutions = await reconcileEnv(needs, {\n    existing,\n    provide: makeProvider(opts),\n  });\n\n  const written = resolutions.filter(\n    (r): r is EnvResolution & { value: string } =>\n      r.status === \"written\" && r.value !== undefined,\n  );\n  appendToFile(\n    envPath,\n    serializeEnvAppend(written.map((r) => ({ env: r.env, value: r.value }))),\n  );\n\n  // .env.example carries the variable names (no secret values), and only for\n  // vars not already documented there.\n  const exampleExisting = readEnvFile(examplePath);\n  const newExampleKeys = needs.filter((n) => !(n.env in exampleExisting));\n  appendToFile(\n    examplePath,\n    serializeEnvAppend(newExampleKeys.map((n) => ({ env: n.env, value: \"\" }))),\n  );\n\n  return resolutions;\n}\n\n/**\n * Prompts for the {@link BindingValueNeed}s that `.env` reconciliation can't\n * collect, returning a `fieldKey -> value` map for buildConfigPlan. Values are\n * not written to `.env` (these fields have no env var). Non-interactive mode\n * uses `values[fieldKey]` if provided, else leaves the field unset.\n */\nexport async function collectBindingValues(\n  needs: BindingValueNeed[],\n  opts: EnvSyncOptions,\n): Promise<Record<string, string>> {\n  const out: Record<string, string> = {};\n  for (const need of needs) {\n    const fromFlag = opts.values?.[need.fieldKey];\n    if (fromFlag !== undefined) {\n      out[need.fieldKey] = fromFlag;\n      continue;\n    }\n    if (opts.nonInteractive) continue;\n    const answer = await text({\n      message: `${need.fieldKey} (${need.resourceType}) — required for databricks.yml`,\n      placeholder: need.description ?? \"leave blank to set before deploy\",\n    });\n    if (isCancel(answer)) continue;\n    const value = (answer ?? \"\").trim();\n    if (value !== \"\") out[need.fieldKey] = value;\n  }\n  return out;\n}\n\n/** Prints a concise summary of what env reconciliation did. */\nexport function reportEnvResolutions(resolutions: EnvResolution[]): void {\n  if (resolutions.length === 0) return;\n  const written = resolutions.filter((r) => r.status === \"written\");\n  const already = resolutions.filter((r) => r.status === \"already-set\");\n  const skipped = resolutions.filter((r) => r.status === \"skipped\");\n\n  if (written.length > 0) {\n    console.log(\n      `${pc.green(\"Wrote to .env:\")} ${written.map((r) => r.env).join(\", \")}`,\n    );\n  }\n  if (already.length > 0) {\n    console.log(pc.dim(`Already set: ${already.map((r) => r.env).join(\", \")}`));\n  }\n  if (skipped.length > 0) {\n    console.log(\n      `${pc.yellow(\"Left unset (set before deploy):\")} ${skipped\n        .map((r) => r.env)\n        .join(\", \")}`,\n    );\n  }\n}\n"],"mappings":"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"}

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

@@ -0,0 +1,25 @@
+import { registryInfoCommand } from "./info.js";
+import { registryListCommand, registrySearchCommand } from "./list.js";
+import { Command } from "commander";
+
+//#region src/cli/commands/registry/index.ts
+/**
+* Parent command for AppKit component registry operations.
+* Subcommands:
+*   - list: Enumerate items available in the registry
+*   - search: Find items by name, description, type, or keyword
+*   - info: Show an item's resource requirements and dependencies
+*
+* Note: `appkit add <item>` is exposed as a top-level command (see add.ts)
+* since it is the primary entry point for consumers.
+*/
+const registryCommand = new Command("registry").description("AppKit component registry commands").addCommand(registryListCommand).addCommand(registrySearchCommand).addCommand(registryInfoCommand).addHelpText("after", `
+Examples:
+  $ appkit registry list
+  $ appkit registry search kpi dashboard
+  $ appkit registry info analytics
+  $ appkit add metric-card`);
+
+//#endregion
+export { registryCommand };
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":[],"sources":["../../../../src/cli/commands/registry/index.ts"],"sourcesContent":["import { Command } from \"commander\";\nimport { registryInfoCommand } from \"./info\";\nimport { registryListCommand, registrySearchCommand } from \"./list\";\n\n/**\n * Parent command for AppKit component registry operations.\n * Subcommands:\n *   - list: Enumerate items available in the registry\n *   - search: Find items by name, description, type, or keyword\n *   - info: Show an item's resource requirements and dependencies\n *\n * Note: `appkit add <item>` is exposed as a top-level command (see add.ts)\n * since it is the primary entry point for consumers.\n */\nexport const registryCommand = new Command(\"registry\")\n  .description(\"AppKit component registry commands\")\n  .addCommand(registryListCommand)\n  .addCommand(registrySearchCommand)\n  .addCommand(registryInfoCommand)\n  .addHelpText(\n    \"after\",\n    `\nExamples:\n  $ appkit registry list\n  $ appkit registry search kpi dashboard\n  $ appkit registry info analytics\n  $ appkit add metric-card`,\n  );\n"],"mappings":";;;;;;;;;;;;;;;AAcA,MAAa,kBAAkB,IAAI,QAAQ,WAAW,CACnD,YAAY,qCAAqC,CACjD,WAAW,oBAAoB,CAC/B,WAAW,sBAAsB,CACjC,WAAW,oBAAoB,CAC/B,YACC,SACA;;;;;4BAMD"}

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

@@ -0,0 +1,45 @@
+import { resolveToken } from "./constants.js";
+import { fetchRegistryItem, isValidItemName, stripNamespace } from "./client.js";
+import { extractRequirements, renderRequirements } from "./requirements.js";
+import { Command } from "commander";
+import process from "node:process";
+import pc from "picocolors";
+
+//#region src/cli/commands/registry/info.ts
+async function runInfo(ref, opts) {
+	const token = resolveToken();
+	const name = stripNamespace(ref);
+	if (!isValidItemName(name)) {
+		console.error(`Invalid registry item name: ${JSON.stringify(ref)}`);
+		process.exit(1);
+	}
+	const item = await fetchRegistryItem(name, token);
+	const rows = extractRequirements(item);
+	if (opts.json) {
+		console.log(JSON.stringify({
+			name: item.name,
+			type: item.type,
+			dependencies: item.dependencies ?? [],
+			registryDependencies: item.registryDependencies ?? [],
+			resources: rows
+		}, null, 2));
+		return;
+	}
+	console.log(pc.bold(item.name));
+	const deps = item.dependencies ?? [];
+	const registryDeps = item.registryDependencies ?? [];
+	if (deps.length > 0) console.log(pc.dim(`  npm dependencies: ${deps.join(", ")}`));
+	if (registryDeps.length > 0) console.log(pc.dim(`  registry dependencies: ${registryDeps.join(", ")}`));
+	console.log(`\n${renderRequirements(item, rows)}`);
+}
+const registryInfoCommand = new Command("info").description("Show an item's resource requirements and dependencies").argument("<item>", "Registry item name, e.g. analytics").option("--json", "Output as JSON").addHelpText("after", `
+Examples:
+  $ appkit registry info analytics
+  $ appkit registry info @databricks-appkit/analytics --json`).action((ref, opts) => runInfo(ref, opts).catch((err) => {
+	console.error(err);
+	process.exit(1);
+}));
+
+//#endregion
+export { registryInfoCommand };
+//# sourceMappingURL=info.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"info.js","names":[],"sources":["../../../../src/cli/commands/registry/info.ts"],"sourcesContent":["import process from \"node:process\";\nimport { Command } from \"commander\";\nimport pc from \"picocolors\";\nimport { fetchRegistryItem, isValidItemName, stripNamespace } from \"./client\";\nimport { resolveToken } from \"./constants\";\nimport { extractRequirements, renderRequirements } from \"./requirements\";\n\nasync function runInfo(ref: string, opts: { json?: boolean }): Promise<void> {\n  const token = resolveToken();\n  // Validate before fetching: the name is interpolated into the fetch path, so\n  // reject non-slug refs (matches the `add` guard) rather than let `/` or `..`\n  // redirect the request to another path in the repo.\n  const name = stripNamespace(ref);\n  if (!isValidItemName(name)) {\n    console.error(`Invalid registry item name: ${JSON.stringify(ref)}`);\n    process.exit(1);\n  }\n  const item = await fetchRegistryItem(name, token);\n  const rows = extractRequirements(item);\n\n  if (opts.json) {\n    console.log(\n      JSON.stringify(\n        {\n          name: item.name,\n          type: item.type,\n          dependencies: item.dependencies ?? [],\n          registryDependencies: item.registryDependencies ?? [],\n          resources: rows,\n        },\n        null,\n        2,\n      ),\n    );\n    return;\n  }\n\n  console.log(pc.bold(item.name));\n  const deps = item.dependencies ?? [];\n  const registryDeps = item.registryDependencies ?? [];\n  if (deps.length > 0) {\n    console.log(pc.dim(`  npm dependencies: ${deps.join(\", \")}`));\n  }\n  if (registryDeps.length > 0) {\n    console.log(pc.dim(`  registry dependencies: ${registryDeps.join(\", \")}`));\n  }\n  console.log(`\\n${renderRequirements(item, rows)}`);\n}\n\nexport const registryInfoCommand = new Command(\"info\")\n  .description(\"Show an item's resource requirements and dependencies\")\n  .argument(\"<item>\", \"Registry item name, e.g. analytics\")\n  .option(\"--json\", \"Output as JSON\")\n  .addHelpText(\n    \"after\",\n    `\nExamples:\n  $ appkit registry info analytics\n  $ appkit registry info @databricks-appkit/analytics --json`,\n  )\n  .action((ref: string, opts: { json?: boolean }) =>\n    runInfo(ref, opts).catch((err) => {\n      console.error(err);\n      process.exit(1);\n    }),\n  );\n"],"mappings":";;;;;;;;AAOA,eAAe,QAAQ,KAAa,MAAyC;CAC3E,MAAM,QAAQ,cAAc;CAI5B,MAAM,OAAO,eAAe,IAAI;AAChC,KAAI,CAAC,gBAAgB,KAAK,EAAE;AAC1B,UAAQ,MAAM,+BAA+B,KAAK,UAAU,IAAI,GAAG;AACnE,UAAQ,KAAK,EAAE;;CAEjB,MAAM,OAAO,MAAM,kBAAkB,MAAM,MAAM;CACjD,MAAM,OAAO,oBAAoB,KAAK;AAEtC,KAAI,KAAK,MAAM;AACb,UAAQ,IACN,KAAK,UACH;GACE,MAAM,KAAK;GACX,MAAM,KAAK;GACX,cAAc,KAAK,gBAAgB,EAAE;GACrC,sBAAsB,KAAK,wBAAwB,EAAE;GACrD,WAAW;GACZ,EACD,MACA,EACD,CACF;AACD;;AAGF,SAAQ,IAAI,GAAG,KAAK,KAAK,KAAK,CAAC;CAC/B,MAAM,OAAO,KAAK,gBAAgB,EAAE;CACpC,MAAM,eAAe,KAAK,wBAAwB,EAAE;AACpD,KAAI,KAAK,SAAS,EAChB,SAAQ,IAAI,GAAG,IAAI,uBAAuB,KAAK,KAAK,KAAK,GAAG,CAAC;AAE/D,KAAI,aAAa,SAAS,EACxB,SAAQ,IAAI,GAAG,IAAI,4BAA4B,aAAa,KAAK,KAAK,GAAG,CAAC;AAE5E,SAAQ,IAAI,KAAK,mBAAmB,MAAM,KAAK,GAAG;;AAGpD,MAAa,sBAAsB,IAAI,QAAQ,OAAO,CACnD,YAAY,wDAAwD,CACpE,SAAS,UAAU,qCAAqC,CACxD,OAAO,UAAU,iBAAiB,CAClC,YACC,SACA;;;8DAID,CACA,QAAQ,KAAa,SACpB,QAAQ,KAAK,KAAK,CAAC,OAAO,QAAQ;AAChC,SAAQ,MAAM,IAAI;AAClB,SAAQ,KAAK,EAAE;EACf,CACH"}

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

@@ -0,0 +1,130 @@
+import { REGISTRY_INDEX_API_URL, REGISTRY_INDEX_URL, REGISTRY_REPO, resolveToken } from "./constants.js";
+import { registryAuthHeaders } from "./client.js";
+import { Command } from "commander";
+import process from "node:process";
+import pc from "picocolors";
+
+//#region src/cli/commands/registry/list.ts
+function isVerified(item) {
+	return item.meta?.verified === true;
+}
+/** Free-text haystack for search matching. */
+function searchHaystack(item) {
+	return [
+		item.name,
+		item.title ?? "",
+		item.description ?? "",
+		itemKind(item),
+		...item.categories ?? []
+	].join(" ").toLowerCase();
+}
+/** True if every whitespace-separated term in `query` appears in the item. */
+function matchesQuery(item, query) {
+	const haystack = searchHaystack(item);
+	return query.toLowerCase().split(/\s+/).filter(Boolean).every((term) => haystack.includes(term));
+}
+/** A friendly kind for the TYPE column: plugin, component, hook, theme, … */
+function itemKind(item) {
+	if ((item.files ?? []).some((f) => f.target?.endsWith("manifest.json") || f.path?.endsWith("manifest.json"))) return "plugin";
+	switch (item.type) {
+		case "registry:component":
+		case "registry:block": return "component";
+		case "registry:hook": return "hook";
+		case "registry:lib": return "lib";
+		case "registry:theme": return "theme";
+		case "registry:ui": return "ui";
+		case "registry:page": return "page";
+		default: return item.type?.replace(/^registry:/, "") || "item";
+	}
+}
+const KIND_COLOR = {
+	plugin: pc.magenta,
+	component: pc.blue,
+	hook: pc.cyan,
+	theme: pc.yellow,
+	lib: pc.green
+};
+function printTable(items) {
+	if (items.length === 0) {
+		console.log(pc.dim("No items found in the registry."));
+		return;
+	}
+	const kinds = items.map(itemKind);
+	const maxName = Math.max(4, ...items.map((i) => i.name.length));
+	const maxKind = Math.max(4, ...kinds.map((k) => k.length));
+	const header = `${"NAME".padEnd(maxName)}  ${"TYPE".padEnd(maxKind)}  VERIFIED  DESCRIPTION`;
+	console.log(pc.bold(header));
+	console.log(pc.dim("─".repeat(header.length)));
+	for (const [i, item] of items.entries()) {
+		const verified = isVerified(item);
+		const kind = kinds[i];
+		const colorKind = KIND_COLOR[kind] ?? pc.white;
+		const name = pc.cyan(item.name.padEnd(maxName));
+		const kindCell = colorKind(kind.padEnd(maxKind));
+		const mark = verified ? pc.green("✓".padEnd(8)) : " ".repeat(8);
+		const desc = item.description ?? item.title ?? "";
+		console.log(`${name}  ${kindCell}  ${mark}  ${verified ? desc : pc.dim(desc)}`);
+	}
+}
+/** Fetches the registry index (token-aware), or exits with a helpful message. */
+async function fetchIndex() {
+	const token = resolveToken();
+	const url = token ? REGISTRY_INDEX_API_URL : REGISTRY_INDEX_URL;
+	let res;
+	try {
+		res = await fetch(url, { headers: registryAuthHeaders(token) });
+	} catch (err) {
+		console.error(pc.red(`Failed to reach the registry at ${url}`));
+		console.error(`  ${err instanceof Error ? err.message : String(err)}`);
+		process.exit(1);
+	}
+	if (res.status === 404 || res.status === 401 || res.status === 403) {
+		console.error(pc.red(`Could not read the registry index from ${REGISTRY_REPO} (HTTP ${res.status}).`));
+		if (!token) console.error("  If the repo is private, set APPKIT_REGISTRY_TOKEN (or GITHUB_TOKEN) to a token with read access.");
+		process.exit(1);
+	}
+	if (!res.ok) {
+		console.error(pc.red(`Registry returned HTTP ${res.status} for ${url}`));
+		process.exit(1);
+	}
+	return (await res.json()).items ?? [];
+}
+function output(items, opts) {
+	if (opts.json) console.log(JSON.stringify(items.map((i) => ({
+		...i,
+		kind: itemKind(i),
+		verified: isVerified(i)
+	})), null, 2));
+	else printTable(items);
+}
+async function runList(opts) {
+	let items = await fetchIndex();
+	if (opts.verified) items = items.filter(isVerified);
+	output(items, opts);
+}
+async function runSearch(query, opts) {
+	let items = await fetchIndex();
+	items = items.filter((i) => matchesQuery(i, query));
+	if (opts.verified) items = items.filter(isVerified);
+	if (items.length === 0 && !opts.json) {
+		console.log(pc.dim(`No items match "${query}".`));
+		return;
+	}
+	output(items, opts);
+}
+const registryListCommand = new Command("list").description("List items available in the AppKit registry").option("--json", "Output as JSON").option("--verified", "Show only verified items").action((opts) => runList(opts).catch((err) => {
+	console.error(err);
+	process.exit(1);
+}));
+const registrySearchCommand = new Command("search").description("Search registry items by name, description, type, or keyword").argument("<query...>", "Search terms (all must match)").option("--json", "Output as JSON").option("--verified", "Show only verified items").addHelpText("after", `
+Examples:
+  $ appkit registry search chart
+  $ appkit registry search kpi dashboard
+  $ appkit registry search plugin --json`).action((query, opts) => runSearch(query.join(" "), opts).catch((err) => {
+	console.error(err);
+	process.exit(1);
+}));
+
+//#endregion
+export { registryListCommand, registrySearchCommand };
+//# sourceMappingURL=list.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"list.js","names":[],"sources":["../../../../src/cli/commands/registry/list.ts"],"sourcesContent":["import process from \"node:process\";\nimport { Command } from \"commander\";\nimport pc from \"picocolors\";\nimport { registryAuthHeaders } from \"./client\";\nimport {\n  REGISTRY_INDEX_API_URL,\n  REGISTRY_INDEX_URL,\n  REGISTRY_REPO,\n  resolveToken,\n} from \"./constants\";\n\ninterface RegistryIndexItem {\n  name: string;\n  type?: string;\n  title?: string;\n  description?: string;\n  categories?: string[];\n  meta?: { verified?: boolean };\n  files?: Array<{ path?: string; target?: string }>;\n}\n\nfunction isVerified(item: RegistryIndexItem): boolean {\n  return item.meta?.verified === true;\n}\n\n/** Free-text haystack for search matching. */\nfunction searchHaystack(item: RegistryIndexItem): string {\n  return [\n    item.name,\n    item.title ?? \"\",\n    item.description ?? \"\",\n    itemKind(item),\n    ...(item.categories ?? []),\n  ]\n    .join(\" \")\n    .toLowerCase();\n}\n\n/** True if every whitespace-separated term in `query` appears in the item. */\nfunction matchesQuery(item: RegistryIndexItem, query: string): boolean {\n  const haystack = searchHaystack(item);\n  return query\n    .toLowerCase()\n    .split(/\\s+/)\n    .filter(Boolean)\n    .every((term) => haystack.includes(term));\n}\n\n/** A friendly kind for the TYPE column: plugin, component, hook, theme, … */\nfunction itemKind(item: RegistryIndexItem): string {\n  const hasManifest = (item.files ?? []).some(\n    (f) =>\n      f.target?.endsWith(\"manifest.json\") || f.path?.endsWith(\"manifest.json\"),\n  );\n  if (hasManifest) return \"plugin\";\n  switch (item.type) {\n    case \"registry:component\":\n    case \"registry:block\":\n      return \"component\";\n    case \"registry:hook\":\n      return \"hook\";\n    case \"registry:lib\":\n      return \"lib\";\n    case \"registry:theme\":\n      return \"theme\";\n    case \"registry:ui\":\n      return \"ui\";\n    case \"registry:page\":\n      return \"page\";\n    default:\n      return item.type?.replace(/^registry:/, \"\") || \"item\";\n  }\n}\n\nconst KIND_COLOR: Record<string, (s: string) => string> = {\n  plugin: pc.magenta,\n  component: pc.blue,\n  hook: pc.cyan,\n  theme: pc.yellow,\n  lib: pc.green,\n};\n\nfunction printTable(items: RegistryIndexItem[]): void {\n  if (items.length === 0) {\n    console.log(pc.dim(\"No items found in the registry.\"));\n    return;\n  }\n  const kinds = items.map(itemKind);\n  const maxName = Math.max(4, ...items.map((i) => i.name.length));\n  const maxKind = Math.max(4, ...kinds.map((k) => k.length));\n  const verifiedCol = \"VERIFIED\";\n  // Pad plain text before coloring so ANSI codes don't break alignment.\n  const header = `${\"NAME\".padEnd(maxName)}  ${\"TYPE\".padEnd(maxKind)}  ${verifiedCol}  DESCRIPTION`;\n  console.log(pc.bold(header));\n  console.log(pc.dim(\"─\".repeat(header.length)));\n  for (const [i, item] of items.entries()) {\n    const verified = isVerified(item);\n    const kind = kinds[i];\n    const colorKind = KIND_COLOR[kind] ?? pc.white;\n    const name = pc.cyan(item.name.padEnd(maxName));\n    const kindCell = colorKind(kind.padEnd(maxKind));\n    const mark = verified\n      ? pc.green(\"✓\".padEnd(verifiedCol.length))\n      : \" \".repeat(verifiedCol.length);\n    const desc = item.description ?? item.title ?? \"\";\n    console.log(\n      `${name}  ${kindCell}  ${mark}  ${verified ? desc : pc.dim(desc)}`,\n    );\n  }\n}\n\n/** Fetches the registry index (token-aware), or exits with a helpful message. */\nasync function fetchIndex(): Promise<RegistryIndexItem[]> {\n  const token = resolveToken();\n  const url = token ? REGISTRY_INDEX_API_URL : REGISTRY_INDEX_URL;\n\n  let res: Awaited<ReturnType<typeof fetch>>;\n  try {\n    res = await fetch(url, { headers: registryAuthHeaders(token) });\n  } catch (err) {\n    console.error(pc.red(`Failed to reach the registry at ${url}`));\n    console.error(`  ${err instanceof Error ? err.message : String(err)}`);\n    process.exit(1);\n  }\n  if (res.status === 404 || res.status === 401 || res.status === 403) {\n    console.error(\n      pc.red(\n        `Could not read the registry index from ${REGISTRY_REPO} (HTTP ${res.status}).`,\n      ),\n    );\n    if (!token) {\n      console.error(\n        \"  If the repo is private, set APPKIT_REGISTRY_TOKEN (or GITHUB_TOKEN) to a token with read access.\",\n      );\n    }\n    process.exit(1);\n  }\n  if (!res.ok) {\n    console.error(pc.red(`Registry returned HTTP ${res.status} for ${url}`));\n    process.exit(1);\n  }\n\n  const data = (await res.json()) as { items?: RegistryIndexItem[] };\n  return data.items ?? [];\n}\n\nfunction output(items: RegistryIndexItem[], opts: { json?: boolean }): void {\n  if (opts.json) {\n    // Surface `kind` + `verified` as top-level fields for easy scripting.\n    console.log(\n      JSON.stringify(\n        items.map((i) => ({\n          ...i,\n          kind: itemKind(i),\n          verified: isVerified(i),\n        })),\n        null,\n        2,\n      ),\n    );\n  } else {\n    printTable(items);\n  }\n}\n\nasync function runList(opts: {\n  json?: boolean;\n  verified?: boolean;\n}): Promise<void> {\n  let items = await fetchIndex();\n  if (opts.verified) items = items.filter(isVerified);\n  output(items, opts);\n}\n\nasync function runSearch(\n  query: string,\n  opts: { json?: boolean; verified?: boolean },\n): Promise<void> {\n  let items = await fetchIndex();\n  items = items.filter((i) => matchesQuery(i, query));\n  if (opts.verified) items = items.filter(isVerified);\n  if (items.length === 0 && !opts.json) {\n    console.log(pc.dim(`No items match \"${query}\".`));\n    return;\n  }\n  output(items, opts);\n}\n\nexport const registryListCommand = new Command(\"list\")\n  .description(\"List items available in the AppKit registry\")\n  .option(\"--json\", \"Output as JSON\")\n  .option(\"--verified\", \"Show only verified items\")\n  .action((opts: { json?: boolean; verified?: boolean }) =>\n    runList(opts).catch((err) => {\n      console.error(err);\n      process.exit(1);\n    }),\n  );\n\nexport const registrySearchCommand = new Command(\"search\")\n  .description(\"Search registry items by name, description, type, or keyword\")\n  .argument(\"<query...>\", \"Search terms (all must match)\")\n  .option(\"--json\", \"Output as JSON\")\n  .option(\"--verified\", \"Show only verified items\")\n  .addHelpText(\n    \"after\",\n    `\nExamples:\n  $ appkit registry search chart\n  $ appkit registry search kpi dashboard\n  $ appkit registry search plugin --json`,\n  )\n  .action((query: string[], opts: { json?: boolean; verified?: boolean }) =>\n    runSearch(query.join(\" \"), opts).catch((err) => {\n      console.error(err);\n      process.exit(1);\n    }),\n  );\n"],"mappings":"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"}