@dbx-tools/cli 0.9.132 → 0.9.136

package/package.json

@@ -34,30 +34,34 @@
   "dependencies": {
     "@clack/prompts": "^1.7.0",
     "@databricks/appkit": "0.81.0",
-    "@dbx-tools/appkit": "^0.9.132",
-    "@dbx-tools/appkit-memory": "^0.9.132",
-    "@dbx-tools/appkit-model-gateway": "^0.9.132",
-    "@dbx-tools/auth": "^0.9.132",
-    "@dbx-tools/auth-gate": "^0.9.132",
-    "@dbx-tools/cli-args": "^0.9.132",
-    "@dbx-tools/cli-service": "^0.9.132",
-    "@dbx-tools/core": "^0.9.132",
-    "@dbx-tools/databricks": "^0.9.132",
-    "@dbx-tools/email": "^0.9.132",
-    "@dbx-tools/lakebase": "^0.9.132",
-    "@dbx-tools/postgres": "^0.9.132",
-    "@dbx-tools/shared-auth": "^0.9.132",
-    "@dbx-tools/shared-core": "^0.9.132",
-    "@dbx-tools/shared-email": "^0.9.132",
-    "@dbx-tools/shared-genie-code": "^0.9.132",
-    "@dbx-tools/shared-model-gateway": "^0.9.132",
-    "@dbx-tools/tunnel": "^0.9.132",
+    "@dbx-tools/appkit": "^0.9.136",
+    "@dbx-tools/appkit-generator": "^0.9.136",
+    "@dbx-tools/appkit-memory": "^0.9.136",
+    "@dbx-tools/appkit-model-gateway": "^0.9.136",
+    "@dbx-tools/appkit-web-search": "^0.9.136",
+    "@dbx-tools/auth": "^0.9.136",
+    "@dbx-tools/auth-gate": "^0.9.136",
+    "@dbx-tools/cli-args": "^0.9.136",
+    "@dbx-tools/cli-service": "^0.9.136",
+    "@dbx-tools/core": "^0.9.136",
+    "@dbx-tools/databricks": "^0.9.136",
+    "@dbx-tools/email": "^0.9.136",
+    "@dbx-tools/lakebase": "^0.9.136",
+    "@dbx-tools/postgres": "^0.9.136",
+    "@dbx-tools/shared-auth": "^0.9.136",
+    "@dbx-tools/shared-core": "^0.9.136",
+    "@dbx-tools/shared-email": "^0.9.136",
+    "@dbx-tools/shared-generator": "^0.9.136",
+    "@dbx-tools/shared-genie-code": "^0.9.136",
+    "@dbx-tools/shared-model-gateway": "^0.9.136",
+    "@dbx-tools/tunnel": "^0.9.136",
     "commander": "^15.0.0",
     "concurrently": "^10.0.3",
     "get-port": "^7.1.0",
     "http-proxy-3": "^1.23.1",
     "pg": "^8.22.0",
     "smol-toml": "1.8.0",
+    "yaml": "^2.9.0",
     "zod": "4.3.6"
   },
   "main": "./lib/index.js",
@@ -115,6 +119,22 @@
         "types": "./lib/src/auth/options.d.ts",
         "default": "./lib/src/auth/options.js"
       },
+      "./brand": {
+        "types": "./lib/src/brand/cli.d.ts",
+        "default": "./lib/src/brand/cli.js"
+      },
+      "./brand/export": {
+        "types": "./lib/src/brand/export.d.ts",
+        "default": "./lib/src/brand/export.js"
+      },
+      "./brand/options": {
+        "types": "./lib/src/brand/options.d.ts",
+        "default": "./lib/src/brand/options.js"
+      },
+      "./brand/run": {
+        "types": "./lib/src/brand/run.d.ts",
+        "default": "./lib/src/brand/run.js"
+      },
       "./graphiti": {
         "types": "./lib/src/graphiti/cli.d.ts",
         "default": "./lib/src/graphiti/cli.js"
@@ -158,7 +178,7 @@
       "./package.json": "./package.json"
     }
   },
-  "version": "0.9.132",
+  "version": "0.9.136",
   "types": "./lib/index.d.ts",
   "dbxToolsConfig": {
     "tags": [
@@ -207,6 +227,22 @@
       "types": "./lib/src/auth/options.d.ts",
       "default": "./lib/src/auth/options.js"
     },
+    "./brand": {
+      "types": "./lib/src/brand/cli.d.ts",
+      "default": "./lib/src/brand/cli.js"
+    },
+    "./brand/export": {
+      "types": "./lib/src/brand/export.d.ts",
+      "default": "./lib/src/brand/export.js"
+    },
+    "./brand/options": {
+      "types": "./lib/src/brand/options.d.ts",
+      "default": "./lib/src/brand/options.js"
+    },
+    "./brand/run": {
+      "types": "./lib/src/brand/run.d.ts",
+      "default": "./lib/src/brand/run.js"
+    },
     "./graphiti": {
       "types": "./lib/src/graphiti/cli.d.ts",
       "default": "./lib/src/graphiti/cli.js"

package/src/brand/cli.ts

@@ -0,0 +1,52 @@
+/**
+ * `dbx brand` researched brand-package export.
+ *
+ * @module
+ */
+
+import { addArgs, parseArgs } from "@dbx-tools/cli-args";
+import { Command } from "commander";
+
+import { BrandExportOptionsSchema } from "./options.ts";
+import { exportBrandFromPrompt } from "./run.ts";
+
+/** Replaceable command boundaries used by tests and embedders. */
+export interface BrandCliDependencies {
+  readonly exportBrandFromPrompt?: typeof exportBrandFromPrompt;
+  readonly writeProgress?: (value: string) => void;
+  readonly writeResult?: (value: unknown) => void;
+}
+
+/** Build the lazily loaded `dbx brand` command. */
+export function buildProgram(name = "dbx brand", dependencies: BrandCliDependencies = {}): Command {
+  const runExport = dependencies.exportBrandFromPrompt ?? exportBrandFromPrompt;
+  const writeProgress =
+    dependencies.writeProgress ?? ((value: string) => process.stderr.write(`${value}\n`));
+  const writeResult =
+    dependencies.writeResult ??
+    ((value: unknown) => process.stdout.write(`${JSON.stringify(value, null, 2)}\n`));
+  const program = addArgs(
+    new Command()
+      .name(name)
+      .description(
+        "Research a brand brief and export brand.yaml with web and mobile visual references",
+      ),
+    BrandExportOptionsSchema,
+  );
+  program
+    .argument("<prompt>", "brand, company, product, or design brief to research")
+    .action(async (prompt: string) => {
+      const options = parseArgs(program, BrandExportOptionsSchema);
+      const result = await runExport(prompt, options, {
+        onProgress(event) {
+          writeProgress(`[${event.stage}] ${event.message}`);
+        },
+      });
+      writeResult({
+        brand: result.brandYamlPath,
+        manifest: result.manifestPath,
+        references: result.referenceCount,
+      });
+    });
+  return program;
+}

package/src/brand/export.ts

@@ -0,0 +1,144 @@
+/**
+ * Brand package filesystem export.
+ *
+ * @module
+ */
+
+import { access, mkdir, rename, rm, writeFile } from "node:fs/promises";
+import path from "node:path";
+import type { BrandResearch } from "@dbx-tools/appkit-generator";
+import type { BrandPackage } from "@dbx-tools/shared-generator";
+import { BrandPackageSchema } from "@dbx-tools/shared-generator";
+import { stringify } from "yaml";
+
+/** Inputs required to write a generated brand package. */
+export interface WriteBrandPackageOptions {
+  readonly outputDirectory: string;
+  readonly prompt: string;
+  readonly brandPackage: BrandPackage;
+  readonly research: BrandResearch;
+  readonly force?: boolean;
+}
+
+/** Files written for a generated brand package. */
+export interface WrittenBrandPackage {
+  readonly outputDirectory: string;
+  readonly brandYamlPath: string;
+  readonly manifestPath: string;
+  readonly referenceCount: number;
+}
+
+function imageExtension(contentType?: string): string {
+  if (!contentType) return ".img";
+  const normalized = contentType.split(";", 1)[0].trim().toLowerCase();
+  switch (normalized) {
+    case "image/avif":
+      return ".avif";
+    case "image/gif":
+      return ".gif";
+    case "image/jpeg":
+      return ".jpg";
+    case "image/png":
+      return ".png";
+    case "image/svg+xml":
+      return ".svg";
+    case "image/webp":
+      return ".webp";
+    default:
+      return ".img";
+  }
+}
+
+function fileSlug(value: string): string {
+  return (
+    value
+      .normalize("NFKD")
+      .replace(/[\u0300-\u036f]/g, "")
+      .toLowerCase()
+      .replace(/[^a-z0-9]+/g, "-")
+      .replace(/^-+|-+$/g, "")
+      .slice(0, 60) || "reference"
+  );
+}
+
+async function writeAtomic(filePath: string, content: string | Uint8Array): Promise<void> {
+  await mkdir(path.dirname(filePath), { recursive: true });
+  const temporaryPath = `${filePath}.${process.pid}.${crypto.randomUUID()}.tmp`;
+  await writeFile(temporaryPath, content);
+  await rename(temporaryPath, filePath);
+}
+
+async function fileExists(filePath: string): Promise<boolean> {
+  try {
+    await access(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Write a normal `brand.yaml` plus research provenance and downloaded visual
+ * references.
+ */
+export async function writeBrandPackage(
+  options: WriteBrandPackageOptions,
+): Promise<WrittenBrandPackage> {
+  const outputDirectory = path.resolve(options.outputDirectory);
+  const brandYamlPath = path.join(outputDirectory, "brand.yaml");
+  const packageExists = await fileExists(brandYamlPath);
+  if (packageExists && !options.force) {
+    throw new Error(`Brand package already exists at ${brandYamlPath}; pass --force to replace it`);
+  }
+  if (options.force) {
+    await rm(path.join(outputDirectory, "references"), { recursive: true, force: true });
+  }
+
+  const visualReferences = structuredClone(options.brandPackage.visualReferences);
+  let referenceCount = 0;
+  for (
+    let referenceIndex = 0;
+    referenceIndex < options.research.visualReferences.length;
+    referenceIndex += 1
+  ) {
+    const researchReference = options.research.visualReferences[referenceIndex];
+    const exportedReference = visualReferences[referenceIndex];
+    if (!exportedReference) continue;
+    for (let imageIndex = 0; imageIndex < researchReference.images.length; imageIndex += 1) {
+      const researchImage = researchReference.images[imageIndex];
+      const exportedImage = exportedReference.images[imageIndex];
+      if (!exportedImage || !researchImage.data) continue;
+      const fileName = `${fileSlug(researchReference.appName)}-${imageIndex + 1}${imageExtension(researchImage.contentType)}`;
+      const relativePath = path.posix.join("references", researchReference.platform, fileName);
+      await writeAtomic(path.join(outputDirectory, relativePath), researchImage.data);
+      exportedImage.localPath = `./${relativePath}`;
+      referenceCount += 1;
+    }
+  }
+
+  const brandPackage = BrandPackageSchema.parse({
+    ...options.brandPackage,
+    visualReferences,
+  });
+  const manifestPath = path.join(outputDirectory, "brand-package.json");
+  await writeAtomic(brandYamlPath, stringify(brandPackage.brand, { indent: 2 }));
+  await writeAtomic(
+    manifestPath,
+    `${JSON.stringify(
+      {
+        prompt: options.prompt,
+        generatedAt: new Date().toISOString(),
+        ...brandPackage,
+      },
+      null,
+      2,
+    )}\n`,
+  );
+
+  return {
+    outputDirectory,
+    brandYamlPath,
+    manifestPath,
+    referenceCount,
+  };
+}

package/src/brand/index.ts

@@ -0,0 +1,13 @@
+// GENERATED by projen watch - DO NOT EDIT.
+// Regenerated from the exporting modules in ./src.
+// Hand edits are overwritten on the next watch; this file is read-only.
+
+export * as cli from "./cli.ts";
+export * as exportModule from "./export.ts";
+export * as options from "./options.ts";
+export * as run from "./run.ts";
+export type { BrandCliDependencies } from "./cli.ts";
+export type { WriteBrandPackageOptions, WrittenBrandPackage } from "./export.ts";
+export { BrandExportOptionsSchema } from "./options.ts";
+export type { BrandExportOptions } from "./options.ts";
+export type { BrandExportCallbacks } from "./run.ts";

package/src/brand/options.ts

@@ -0,0 +1,48 @@
+/**
+ * `dbx brand` option contracts.
+ *
+ * @module
+ */
+
+import { DatabricksAuthOptionsSchema } from "@dbx-tools/auth/config";
+import { z } from "zod";
+
+/** Options for exporting one researched brand package. */
+export const BrandExportOptionsSchema = z
+  .object({
+    profile: DatabricksAuthOptionsSchema.shape.profile,
+    name: z.string().trim().min(1).optional().describe("Known canonical brand name."),
+    website: z.string().url().optional().describe("Known official HTTPS website."),
+    output: z
+      .string()
+      .trim()
+      .min(1)
+      .default("branding")
+      .describe("Output directory for brand.yaml, provenance, and visual references."),
+    model: z
+      .string()
+      .trim()
+      .min(1)
+      .optional()
+      .describe("Optional Databricks model preference for brand synthesis."),
+    maxSources: z.coerce
+      .number()
+      .int()
+      .min(1)
+      .max(8)
+      .default(4)
+      .describe("Maximum general web sources to read."),
+    sourceMaxLength: z.coerce
+      .number()
+      .int()
+      .min(1_000)
+      .max(20_000)
+      .default(8_000)
+      .describe("Maximum characters retained from each source page."),
+    force: z.boolean().default(false).describe("Replace files in an existing output directory."),
+  })
+  .strict()
+  .describe("Options for exporting a researched brand package.");
+
+/** Resolved brand export options. */
+export type BrandExportOptions = z.output<typeof BrandExportOptionsSchema>;

package/src/brand/run.ts

@@ -0,0 +1,85 @@
+/**
+ * Standalone researched brand generation for the consolidated CLI.
+ *
+ * @module
+ */
+
+import type { BrandResearch } from "@dbx-tools/appkit-generator";
+import { generateBrandPackage } from "@dbx-tools/appkit-generator/generate";
+import {
+  runWebAssetPageFetch,
+  runWebFetch,
+  runWebImageFetch,
+} from "@dbx-tools/appkit-web-search/fetch";
+import { createWebSearchRuntime } from "@dbx-tools/appkit-web-search/runtime";
+import { runWebSearch } from "@dbx-tools/appkit-web-search/search";
+import { createWorkspaceClient } from "@dbx-tools/databricks/workspace-client";
+import type { BrandGenerationProgressEvent } from "@dbx-tools/shared-generator";
+
+import { writeBrandPackage, type WrittenBrandPackage } from "./export.ts";
+import type { BrandExportOptions } from "./options.ts";
+
+/** Optional observers for one CLI brand generation run. */
+export interface BrandExportCallbacks {
+  readonly onProgress?: (event: BrandGenerationProgressEvent) => void | Promise<void>;
+}
+
+/**
+ * Research a freeform brand brief, synthesize a portable context, and export
+ * the package to disk.
+ */
+export async function exportBrandFromPrompt(
+  prompt: string,
+  options: BrandExportOptions,
+  callbacks: BrandExportCallbacks = {},
+): Promise<WrittenBrandPackage> {
+  const workspaceClient = await createWorkspaceClient({
+    ...(options.profile ? { profile: options.profile } : {}),
+  });
+  const host = (await workspaceClient.config.getHost()).toString();
+  const runtime = createWebSearchRuntime({
+    ...(options.model ? { model: options.model } : {}),
+  });
+  let research: BrandResearch | undefined;
+  const brandPackage = await generateBrandPackage(
+    {
+      prompt,
+      ...(options.name ? { name: options.name } : {}),
+      ...(options.website ? { website: options.website } : {}),
+    },
+    {
+      client: {
+        search: (request, signal) =>
+          runWebSearch(
+            request,
+            runtime,
+            {
+              client: workspaceClient,
+              host,
+              ...(options.profile ? { cacheIdentity: `profile:${options.profile}` } : {}),
+            },
+            signal,
+          ),
+        fetch: (request, signal) => runWebFetch(request, runtime, signal),
+        fetchAssetPage: (request, signal) => runWebAssetPageFetch(request, runtime, signal),
+        fetchImage: (request, signal) => runWebImageFetch(request, runtime, signal),
+      },
+      workspaceClient,
+      ...(options.model ? { model: options.model } : {}),
+      maxSources: options.maxSources,
+      sourceMaxLength: options.sourceMaxLength,
+      ...(callbacks.onProgress ? { onProgress: callbacks.onProgress } : {}),
+      onResearch(value) {
+        research = value;
+      },
+    },
+  );
+  if (!research) throw new Error("Brand generation completed without research provenance");
+  return writeBrandPackage({
+    outputDirectory: options.output,
+    prompt,
+    brandPackage,
+    research,
+    force: options.force,
+  });
+}

package/src/cli.ts

@@ -4,6 +4,7 @@
  * `dev` bootstraps or repairs a workspace and forwards to projen.
  * `appkit` provides AppKit environment helpers.
  * `auth` manages Databricks OAuth and access tokens.
+ * `brand` researches and exports portable brand packages.
  * `tunnel` runs a public portr tunnel with passwordless access gating.
  *
  * Feature commands load their sibling packages only when selected and forward
@@ -88,7 +89,7 @@ export function buildProgram(name: string = PROGRAM_NAMES[0]): Command {
   const program = new Command()
     .name(name)
     .description(
-      "Databricks developer tools: workspace lifecycle, AppKit env, auth, tunnels, and local proxies",
+      "Databricks developer tools: workspace lifecycle, AppKit env, auth, brand generation, tunnels, and local proxies",
     )
     .enablePositionalOptions()
     .showHelpAfterError()
@@ -119,6 +120,13 @@ export function buildProgram(name: string = PROGRAM_NAMES[0]): Command {
     async () => (await import("./auth/cli.ts")).buildProgram,
   );
 
+  addForwardedCommand(
+    program,
+    "brand",
+    "Research and export a portable brand package",
+    async () => (await import("./brand/cli.ts")).buildProgram,
+  );
+
   addForwardedCommand(
     program,
     "tunnel",
@@ -163,6 +171,7 @@ export async function buildDocumentationProgram(name: string = PROGRAM_NAMES[0])
   const children = [
     (await import("./appkit/cli.ts")).buildProgram("appkit"),
     (await import("./auth/cli.ts")).buildProgram("auth"),
+    (await import("./brand/cli.ts")).buildProgram("brand"),
     (await import("./tunnel/cli.ts")).buildProgram("tunnel"),
     (await import("./lakebase-proxy/cli.ts")).buildProgram("lakebase-proxy"),
     (await import("./model-gateway/cli.ts")).buildProgram("model-gateway"),

package/src/tunnel/cli.ts

@@ -132,6 +132,7 @@ async function run(raw: TunnelOptions, command: readonly string[]): Promise<void
     forwardHeaders: resolved.gate.forwardHeaders,
     gatePaths: resolved.gate.gatePaths,
     brandName: resolved.gate.brandName,
+    passkeyNamePrefix: resolved.gate.passkeyNamePrefix,
     bindHosts: resolved.bindHosts,
   });
 

package/src/tunnel/options.ts

@@ -45,6 +45,9 @@ export const TunnelOptionsSchema = z
     allow: list("Email allow-list patterns.").meta({ env: "TUNNEL_AUTH_ALLOW" }),
     subject: text("Verification email subject.").meta({ env: "TUNNEL_AUTH_SUBJECT" }),
     brandName: text("Verification email brand name.").meta({ env: "TUNNEL_AUTH_BRAND_NAME" }),
+    passkeyNamePrefix: text("Prefix for humanized tunnel passkey names.").meta({
+      env: "TUNNEL_AUTH_PASSKEY_NAME_PREFIX",
+    }),
     message: text("Verification email message.").meta({ env: "TUNNEL_AUTH_MESSAGE" }),
     sessionTtlSeconds: z.coerce
       .number<number>()
@@ -127,6 +130,7 @@ export function resolveTunnelOptions(options: TunnelOptions): ResolvedTunnelOpti
     allow: options.allow,
     subject: options.subject,
     brandName: options.brandName,
+    passkeyNamePrefix: options.passkeyNamePrefix,
     message: options.message,
     // Coerced, not resolved: the plugin owns the env name and the default for
     // these, so the flag is passed through as the `config` value it expects and

package/src/tunnel/proxy.ts

@@ -46,6 +46,8 @@ export interface ProxyOptions {
   gatePaths?: readonly string[];
   /** Brand name for the hosted login page shown on a denied browser navigation. */
   brandName?: string;
+  /** Prefix added before the humanized tunnel subdomain in new passkey names. */
+  passkeyNamePrefix?: string;
   /**
    * Addresses to listen on. Defaults to a single `0.0.0.0` (every interface),
    * the portr/platform case. Pass specific interface IPs to expose the gate on
@@ -77,6 +79,7 @@ async function handleAuthRoute(
   path: string,
   gate: AuthGateApi,
   brandName: string,
+  passkeyNamePrefix?: string,
 ): Promise<boolean> {
   if (!tunnelGate.isAuthPath(path)) return false;
   if (tunnelGate.wantsHostedLogin(request)) {
@@ -84,6 +87,7 @@ async function handleAuthRoute(
     response.end(
       tunnelLoginPage.loginPageHtml({
         brandName,
+        passkeyNamePrefix,
         returnTo: tunnelGate.loginReturnTo(request),
       }),
     );
@@ -126,13 +130,20 @@ export async function startProxy(options: ProxyOptions): Promise<void> {
     void (async () => {
       const path = (request.url ?? "/").split("?")[0] ?? "/";
       const brandName = options.brandName ?? "this app";
-      if (gate && (await handleAuthRoute(request, response, path, gate, brandName))) return;
+      const passkeyNamePrefix = options.passkeyNamePrefix;
+      if (
+        gate &&
+        (await handleAuthRoute(request, response, path, gate, brandName, passkeyNamePrefix))
+      ) {
+        return;
+      }
       if ((await decide(request)) === "deny") {
         // A denied browser navigation gets the hosted login page; anything else
         // (an XHR, a /ws upgrade probe, a non-HTML fetch) gets the 401 JSON.
         if (gate && tunnelGate.wantsLoginPage(request)) {
           const html = tunnelLoginPage.loginPageHtml({
             brandName,
+            passkeyNamePrefix,
             returnTo: tunnelGate.requestReturnTo(request),
           });
           response.writeHead(401, { "content-type": "text/html; charset=utf-8" });