jitsu-cli 2.14.0-beta.8 → 2.14.0-beta.93

package/src/commands/config/resources.ts

@@ -0,0 +1,110 @@
+// Single source of truth for the `jitsu config <noun>` command tree.
+// `kind` selects which verb handlers apply; `type` is the segment used in
+// /api/{workspaceId}/config/{type} for standard config objects.
+
+export type ResourceKind = "configObject" | "workspace" | "link" | "profile-builder";
+
+export type Resource = {
+  noun: string;
+  aliases: string[];
+  kind: ResourceKind;
+  type?: string;
+  supportsTest?: boolean;
+  // Description used in `--help`.
+  description: string;
+};
+
+export const resources: Resource[] = [
+  {
+    noun: "workspaces",
+    aliases: ["workspace"],
+    kind: "workspace",
+    description: "Workspaces accessible to the current user",
+  },
+  {
+    noun: "destinations",
+    aliases: ["destination", "dest"],
+    kind: "configObject",
+    type: "destination",
+    supportsTest: true,
+    description: "Destinations (warehouses, databases, services receiving events)",
+  },
+  {
+    noun: "streams",
+    aliases: ["stream"],
+    kind: "configObject",
+    type: "stream",
+    supportsTest: true,
+    description: "Event streams (formerly known as sources)",
+  },
+  {
+    noun: "functions",
+    aliases: ["function", "fn"],
+    kind: "configObject",
+    type: "function",
+    description: "User-defined functions (UDFs). For dev workflow see `jitsu deploy`.",
+  },
+  {
+    noun: "services",
+    aliases: ["service"],
+    kind: "configObject",
+    type: "service",
+    supportsTest: true,
+    description: "External connector services (Airbyte protocol)",
+  },
+  {
+    noun: "domains",
+    aliases: ["domain"],
+    kind: "configObject",
+    type: "domain",
+    description: "Custom ingestion domains",
+  },
+  {
+    noun: "misc",
+    aliases: [],
+    kind: "configObject",
+    type: "misc",
+    description: "Miscellaneous configuration entities (free-form)",
+  },
+  {
+    noun: "notifications",
+    aliases: ["notification"],
+    kind: "configObject",
+    type: "notification",
+    description: "Alert channels (email/Slack)",
+  },
+  {
+    noun: "connections",
+    aliases: ["connection", "link", "links"],
+    kind: "link",
+    description: "Connections between streams/services and destinations",
+  },
+  {
+    noun: "profile-builders",
+    aliases: ["profile-builder"],
+    kind: "profile-builder",
+    description: "Profile builders (identity stitching)",
+  },
+];
+
+export type Verb = "list" | "get" | "create" | "update" | "delete" | "test";
+
+// Which verbs apply to a given resource kind.
+export function verbsFor(kind: ResourceKind): Verb[] {
+  switch (kind) {
+    case "configObject":
+      return ["list", "get", "create", "update", "delete"];
+    case "workspace":
+      return ["list", "get", "create", "update", "delete"];
+    case "link":
+      // link has no per-id GET; list+create(upsert)+update(alias)+delete
+      return ["list", "create", "update", "delete"];
+    case "profile-builder":
+      return ["list", "create", "update", "delete"];
+  }
+}
+
+export function findResource(name: string): Resource | undefined {
+  const lower = name.toLowerCase();
+  return resources.find(r => r.noun === lower || r.aliases.includes(lower));
+}

package/src/commands/default-workspace.ts

@@ -0,0 +1,44 @@
+import { ApiClient, ApiError } from "../lib/api-client";
+import { authFilePath, readAuthFile, resolveAuth, updateAuthFile } from "../lib/auth-file";
+import { red } from "../lib/chalk-code-highlight";
+
+export type DefaultWorkspaceOpts = {
+  host?: string;
+  apikey?: string;
+};
+
+export async function setDefaultWorkspace(idOrSlug: string, opts: DefaultWorkspaceOpts) {
+  try {
+    const auth = resolveAuth(opts);
+    const client = new ApiClient(auth);
+    let workspace: { id: string; slug?: string; name?: string };
+    try {
+      workspace = await client.request({
+        method: "GET",
+        path: `/api/workspace/${encodeURIComponent(idOrSlug)}`,
+      });
+    } catch (e) {
+      if (e instanceof ApiError && e.status === 404) {
+        throw new Error(`Workspace '${idOrSlug}' not found (or you don't have access)`);
+      }
+      throw e;
+    }
+    updateAuthFile({ defaultWorkspace: workspace.id });
+    const label = workspace.slug ? `${workspace.slug} (${workspace.id})` : workspace.id;
+    console.log(`Default workspace set to ${label}.`);
+    console.log(`Saved to ${authFilePath()}.`);
+  } catch (e) {
+    console.error(red(`Error: ${e instanceof Error ? e.message : String(e)}`));
+    process.exit(1);
+  }
+}
+
+export async function unsetDefaultWorkspace() {
+  const file = readAuthFile();
+  if (!file?.defaultWorkspace) {
+    console.log("No default workspace is set.");
+    return;
+  }
+  updateAuthFile({ defaultWorkspace: undefined });
+  console.log("Default workspace unset.");
+}

package/src/commands/deploy.ts

@@ -3,7 +3,6 @@ import { homedir } from "os";
 import inquirer from "inquirer";
 import { existsSync, readdirSync, readFileSync } from "fs";
 import { loadPackageJson } from "./shared";
-import fetch from "node-fetch";
 import cuid from "cuid";
 import { b, green, red } from "../lib/chalk-code-highlight";
 import { getFunctionFromFilePath } from "../lib/compiled-function";
@@ -144,6 +143,11 @@ async function deployFunctions(
     profileBuilders = ((await res.json()) as any).profileBuilders as any[];
   }
 
+  // Fetch the existing function list once for slug/id resolution. Previously
+  // every deployFunction() call refetched the whole list (with code blobs) —
+  // O(N) requests per deploy, each pulling all N rows from the console DB.
+  const existingFunctions = await fetchExistingFunctions({ host, apikey, workspaceId: workspace.id! });
+
   for (const file of selectedFiles) {
     console.log(
       `${b(`𝑓`)} Deploying function ${b(path.basename(file))} to workspace ${workspace.name} (${host}/${
@@ -151,27 +155,98 @@ async function deployFunctions(
       })`
     );
     await deployFunction(
+      projectDir,
       { host, apikey },
       packageJson,
       workspace,
       kind,
       path.resolve(functionsDir, file),
-      profileBuilders
+      profileBuilders,
+      existingFunctions
     );
   }
 }
 
+// Cache of functions already present in the workspace. byId and bySlug share
+// object identity so a single mutation visible from both. `slug` is tracked
+// per entry so we can detect (and reflect) renames on PUT.
+type ExistingFunction = { id: string; slug?: string };
+type ExistingFunctionsCache = {
+  bySlug: Map<string, ExistingFunction>;
+  byId: Map<string, ExistingFunction>;
+};
+
+async function fetchExistingFunctions({
+  host,
+  apikey,
+  workspaceId,
+}: {
+  host?: string;
+  apikey?: string;
+  workspaceId?: string;
+}): Promise<ExistingFunctionsCache> {
+  const res = await fetch(`${host}/api/${workspaceId}/config/function`, {
+    headers: { Authorization: `Bearer ${apikey}` },
+  });
+  if (!res.ok) {
+    console.error(red(`Cannot list existing functions:\n${b(await res.text())}`));
+    process.exit(1);
+  }
+  const { objects } = (await res.json()) as { objects: { id: string; slug?: string }[] };
+  const bySlug = new Map<string, ExistingFunction>();
+  const byId = new Map<string, ExistingFunction>();
+  for (const f of objects) {
+    const entry: ExistingFunction = { id: f.id, slug: f.slug };
+    byId.set(f.id, entry);
+    if (f.slug) bySlug.set(f.slug, entry);
+  }
+  return { bySlug, byId };
+}
+
+// Update the cache after a successful POST. Both maps must reflect the new
+// function so a later file with the same slug/id in this same deploy run
+// switches to PUT instead of trying a second POST.
+function cacheAfterCreate(cache: ExistingFunctionsCache, id: string, slug: string | undefined) {
+  const entry: ExistingFunction = { id, slug };
+  cache.byId.set(id, entry);
+  if (slug) cache.bySlug.set(slug, entry);
+}
+
+// Update the cache after a successful PUT. Preserves the previous re-fetch
+// semantics for slug renames: the old slug is no longer pointing at this id
+// on the server, so drop it from the slug index and install the new one.
+function cacheAfterUpdate(cache: ExistingFunctionsCache, id: string, newSlug: string | undefined) {
+  const entry = cache.byId.get(id);
+  if (!entry) {
+    // Function existed only on the server, not in our hoisted cache (shouldn't
+    // normally happen since the PUT branch only runs when we resolved an id).
+    // Insert defensively so later files in this run see it.
+    cacheAfterCreate(cache, id, newSlug);
+    return;
+  }
+  if (entry.slug && entry.slug !== newSlug) {
+    cache.bySlug.delete(entry.slug);
+  }
+  entry.slug = newSlug;
+  if (newSlug) cache.bySlug.set(newSlug, entry);
+}
+
 async function deployFunction(
+  projectDir: string,
   { host, apikey }: Args,
   packageJson: any,
   workspace: Workspace,
   kind: "function" | "profile",
   file: string,
-  profileBuilders: any[] = []
+  profileBuilders: any[] = [],
+  existingFunctions: ExistingFunctionsCache = {
+    bySlug: new Map(),
+    byId: new Map(),
+  }
 ) {
   const code = readFileSync(file, "utf-8");
 
-  const wrapped = await getFunctionFromFilePath(file, kind, profileBuilders);
+  const wrapped = await getFunctionFromFilePath(projectDir, file, kind, profileBuilders);
   const meta = wrapped.meta;
   if (meta) {
     console.log(`  meta: slug=${meta.slug}, name=${meta.name || "not set"}`);
@@ -181,18 +256,8 @@ async function deployFunction(
   }
   let existingFunctionId: string | undefined;
   if (meta.slug) {
-    const res = await fetch(`${host}/api/${workspace.id}/config/function`, {
-      headers: {
-        Authorization: `Bearer ${apikey}`,
-      },
-    });
-    if (!res.ok) {
-      console.error(red(`Cannot add function to workspace:\n${b(await res.text())}`));
-      process.exit(1);
-    } else {
-      const existing = (await res.json()) as any;
-      existingFunctionId = existing.objects.find(f => f.slug === meta.slug || f.id === meta.id)?.id;
-    }
+    existingFunctionId =
+      existingFunctions.bySlug.get(meta.slug)?.id ?? (meta.id ? existingFunctions.byId.get(meta.id)?.id : undefined);
   }
   let functionPayload = {};
   if (kind === "profile") {
@@ -230,6 +295,11 @@ async function deployFunction(
       console.error(red(`Cannot add function to workspace:\n${b(await res.text())}`));
       process.exit(1);
     } else {
+      // Reflect the new function in the hoisted cache so a later file in
+      // this same deploy that targets the same slug switches to PUT instead
+      // of POSTing a duplicate. Matches the pre-hoist behavior where each
+      // file re-fetched the list.
+      cacheAfterCreate(existingFunctions, id, meta.slug);
       console.log(`Function ${b(meta.name)} was successfully added to workspace ${workspace.name} with id: ${b(id)}`);
     }
   } else {
@@ -255,6 +325,10 @@ async function deployFunction(
       console.error(red(`⚠ Cannot deploy function ${b(meta.slug)}(${id}):\n${b(await res.text())}`));
       process.exit(1);
     } else {
+      // Slug may have been renamed by this PUT — update the slug index so a
+      // later file deploying under the old slug (if any) creates a new
+      // function instead of clobbering this one.
+      cacheAfterUpdate(existingFunctions, id, meta.slug);
       console.log(`${green(`✓`)} ${b(meta.name)} deployed successfully!`);
     }
   }

package/src/commands/spec.ts

@@ -0,0 +1,32 @@
+import { Command } from "commander";
+import { red } from "../lib/chalk-code-highlight";
+import { normalizeHost, readAuthFile, resolveAuth } from "../lib/auth-file";
+import { fetchSpec } from "../lib/spec";
+import { DEFAULT_OUTPUT, SUPPORTED_OUTPUTS, print } from "../lib/renderer";
+
+export function buildSpecCommand(): Command {
+  return new Command("spec")
+    .description("Print the live OpenAPI spec served at /api/spec")
+    .option("-o, --output <format>", `Output format: ${SUPPORTED_OUTPUTS.join(", ")}`, DEFAULT_OUTPUT)
+    .option("-h, --host <host>", "Jitsu host (overrides ~/.jitsu/jitsu-cli.json)")
+    .option("-k, --apikey <api-key>", "API key (overrides ~/.jitsu/jitsu-cli.json)")
+    .action(async (opts: { output?: string; host?: string; apikey?: string }) => {
+      try {
+        // Pass a placeholder apikey if missing — /api/spec is public, but resolveAuth
+        // expects an apikey. Fall back to a synthetic one if user has no auth file.
+        const auth = (() => {
+          try {
+            return resolveAuth(opts);
+          } catch {
+            const host = opts.host ?? readAuthFile()?.host ?? "https://use.jitsu.com";
+            return { host: normalizeHost(host), apikey: "anonymous" };
+          }
+        })();
+        const spec = await fetchSpec(auth);
+        print(spec, opts.output);
+      } catch (e) {
+        console.error(red(`Error: ${e instanceof Error ? e.message : String(e)}`));
+        process.exit(1);
+      }
+    });
+}

package/src/index.ts

@@ -8,12 +8,27 @@ import { test } from "./commands/test";
 
 import { jitsuCliVersion, jitsuCliPackageName } from "./lib/version";
 import { whoami } from "./commands/whoami";
+import { buildConfigCommand } from "./commands/config";
+import { buildSpecCommand } from "./commands/spec";
+import { setDefaultWorkspace, unsetDefaultWorkspace } from "./commands/default-workspace";
+import { preprocessArgv } from "./lib/body-fields";
 
-console.log(figlet.textSync("Jitsu CLI", { horizontalLayout: "full" }));
+// Pull ad-hoc body field flags (--name=val, --credentials.password=...) out of argv
+// before Commander parses it. Reserved option names are left in place.
+process.argv = preprocessArgv(process.argv);
+
+// Figlet banner is decorative — write it to stderr so `jitsu config ... -o json | jq`
+// works without filtering. Skip it entirely when stdout is being piped or for spec output
+// (which is also typically piped to other tools).
+const isPipedStdout = !process.stdout.isTTY;
+if (!isPipedStdout) {
+  process.stderr.write(figlet.textSync("Jitsu CLI", { horizontalLayout: "full" }) + "\n");
+}
 
 const p = new Command();
 
-p.name(jitsuCliPackageName).description("CLI command to create, test and deploy extensions for Jitsu Next");
+p.name(jitsuCliPackageName).description("Jitsu CLI — manage workspaces, configuration objects, and extensions");
+
 p.command("init")
   .description("Initialize a new Jitsu extension project")
   .arguments("[dir]")
@@ -31,19 +46,6 @@ p.command("test")
   .option("-d, --dir <dir>", "the directory of project. (Optional). By default, current directory is used")
   .action(test);
 
-// p.command("run")
-//   .description("Check extensions on provided event, config and persistent storage state")
-//   .option("-d, --dir <dir>", "the directory of project. (Optional). By default, current directory is used")
-//   .option(
-//     "-n, --name <name>",
-//     "name of function file to check (optional). Required if multiple functions are defined in project"
-//   )
-//   .option("-t, --type <type>", "entity type to run", "function")
-//   .requiredOption("-e, --event <file_or_json>", "path to file with event json or event json as a string")
-//   .option("-p, --props <file_or_json>", "path to file with config json or config json as a string. (Optional)")
-//   .option("-s, --store <file_or_json>", "path to file with state json or state json as a string. (Optional)")
-//   .action(run);
-
 p.command("whoami")
   .description("Check if current user is logged in. Shows user's info if logged in")
   .option("-h, --host <host>", "Jitsu host or base url", "https://use.jitsu.com")
@@ -56,6 +58,7 @@ p.command("login")
   .option("-h, --host <host>", "Jitsu host or base url", "https://use.jitsu.com")
   .option("-k, --apikey <api-key>", "Jitsu user's Api Key. (Optional). Disables interactive login.")
   .action(login);
+
 p.command("logout").description("Logout").option("-f, --force", "Do not ask for confirmation").action(logout);
 
 p.command("deploy")
@@ -75,9 +78,23 @@ p.command("deploy")
   .option("-n, --name <name...>", "limit deploy to provided entities only. (Optional)")
   .action(deploy);
 
-//version
+p.command("set-default-workspace")
+  .description(
+    "Save a default workspace to ~/.jitsu/jitsu-cli.json. Subsequent `jitsu config` commands use it when -w is omitted."
+  )
+  .argument("<id-or-slug>", "Workspace id or slug")
+  .option("-h, --host <host>", "Jitsu host (overrides ~/.jitsu/jitsu-cli.json)")
+  .option("-k, --apikey <api-key>", "API key in form keyId:secret (overrides ~/.jitsu/jitsu-cli.json)")
+  .action(setDefaultWorkspace);
+
+p.command("unset-default-workspace")
+  .description("Remove the saved default workspace from ~/.jitsu/jitsu-cli.json")
+  .action(unsetDefaultWorkspace);
+
+p.addCommand(buildConfigCommand());
+p.addCommand(buildSpecCommand());
+
 p.version(jitsuCliPackageName + " " + jitsuCliVersion, "-v, --version");
-//help
 p.helpOption("--help", "display help for command");
 
 p.parse();

package/src/lib/api-client.ts

@@ -0,0 +1,64 @@
+import { AuthInfo } from "./auth-file";
+
+export type ApiRequest = {
+  method?: "GET" | "POST" | "PUT" | "DELETE" | "PATCH";
+  path: string;
+  query?: Record<string, string | number | boolean | undefined | null>;
+  body?: unknown;
+};
+
+export class ApiError extends Error {
+  status: number;
+  payload: unknown;
+  constructor(status: number, message: string, payload: unknown) {
+    super(message);
+    this.status = status;
+    this.payload = payload;
+  }
+}
+
+export class ApiClient {
+  constructor(private auth: AuthInfo) {}
+
+  url(path: string, query?: ApiRequest["query"]): string {
+    const base = this.auth.host;
+    const p = path.startsWith("/") ? path : `/${path}`;
+    if (!query) return `${base}${p}`;
+    const qs = Object.entries(query)
+      .filter(([, v]) => v !== undefined && v !== null && v !== "")
+      .map(([k, v]) => `${encodeURIComponent(k)}=${encodeURIComponent(String(v))}`)
+      .join("&");
+    return qs ? `${base}${p}?${qs}` : `${base}${p}`;
+  }
+
+  async request<T = unknown>(req: ApiRequest): Promise<T> {
+    const method = req.method ?? "GET";
+    const headers: Record<string, string> = {
+      Accept: "application/json",
+      Authorization: `Bearer ${this.auth.apikey}`,
+    };
+    let body: string | undefined;
+    if (req.body !== undefined) {
+      headers["Content-Type"] = "application/json";
+      body = JSON.stringify(req.body);
+    }
+    const res = await fetch(this.url(req.path, req.query), { method, headers, body });
+    const text = await res.text();
+    let parsed: unknown = text;
+    if (text && res.headers.get("content-type")?.includes("application/json")) {
+      try {
+        parsed = JSON.parse(text);
+      } catch {
+        // fall through with raw text
+      }
+    }
+    if (!res.ok) {
+      const msg =
+        (parsed && typeof parsed === "object" && "message" in (parsed as any)
+          ? String((parsed as any).message)
+          : undefined) ?? `HTTP ${res.status} ${method} ${req.path}`;
+      throw new ApiError(res.status, msg, parsed);
+    }
+    return parsed as T;
+  }
+}

package/src/lib/auth-file.ts

@@ -0,0 +1,83 @@
+import * as fs from "fs";
+import { mkdirSync, readFileSync, writeFileSync } from "fs";
+import { homedir } from "os";
+
+export type AuthInfo = { host: string; apikey: string };
+
+export type AuthFile = {
+  host?: string;
+  apikey?: string;
+  defaultWorkspace?: string;
+};
+
+const DEFAULT_HOST = "https://use.jitsu.com";
+
+export function authFilePath(): string {
+  return `${homedir()}/.jitsu/jitsu-cli.json`;
+}
+
+export function readAuthFile(): AuthFile | undefined {
+  const path = authFilePath();
+  if (!fs.existsSync(path)) return undefined;
+  return JSON.parse(readFileSync(path, { encoding: "utf-8" }));
+}
+
+// Merge `patch` into the existing auth file, creating the file (and parent dir)
+// if necessary. Setting a field to `undefined` removes it.
+export function updateAuthFile(patch: Partial<AuthFile>): AuthFile {
+  const path = authFilePath();
+  const existing = readAuthFile() ?? {};
+  const next: AuthFile = { ...existing };
+  for (const [k, v] of Object.entries(patch)) {
+    if (v === undefined) delete (next as any)[k];
+    else (next as any)[k] = v;
+  }
+  mkdirSync(`${homedir()}/.jitsu`, { recursive: true });
+  writeFileSync(path, JSON.stringify(next, null, 2));
+  return next;
+}
+
+export function readDefaultWorkspace(): string | undefined {
+  return readAuthFile()?.defaultWorkspace;
+}
+
+// Resolve host + apikey for an authenticated CLI command. Order of precedence:
+//   1. --host / --apikey flags
+//   2. ~/.jitsu/jitsu-cli.json
+//   3. JITSU_HOST / JITSU_APIKEY env vars
+//   4. https://use.jitsu.com (host only)
+export function resolveAuth(opts: { host?: string; apikey?: string }): AuthInfo {
+  let host = opts.host;
+  let apikey = opts.apikey;
+
+  if (!host || !apikey) {
+    const file = readAuthFile();
+    if (file) {
+      if (!host) host = file.host;
+      if (!apikey) apikey = file.apikey;
+    }
+  }
+
+  if (!host) host = process.env.JITSU_HOST;
+  if (!apikey) apikey = process.env.JITSU_APIKEY;
+  if (!host) host = DEFAULT_HOST;
+
+  if (!apikey) {
+    throw new Error("Not authenticated. Run `jitsu login`, set JITSU_APIKEY, or pass --apikey <key>.");
+  }
+
+  return { host: normalizeHost(host), apikey };
+}
+
+export function normalizeHost(host: string): string {
+  let url = host;
+  if (!url.startsWith("http")) {
+    if (url.startsWith("localhost") || /^[0-9]+\.[0-9]+\.[0-9]+\.[0-9]+/.test(url)) {
+      url = "http://" + url;
+    } else {
+      url = "https://" + url;
+    }
+  }
+  if (url.endsWith("/")) url = url.slice(0, -1);
+  return url;
+}

package/src/lib/body-builder.ts

@@ -0,0 +1,68 @@
+import * as fs from "fs";
+import yaml from "js-yaml";
+import { parseScalar, setDottedPath } from "./dotted";
+
+export type BodySources = {
+  // Path to a yaml/json file. `-` means stdin.
+  file?: string;
+  // Inline JSON string (full body or partial).
+  json?: string;
+  // Already-parsed dotted-path fields, e.g. { "credentials.password": "secret" }.
+  fields?: Record<string, string>;
+};
+
+// Builds a single request body by merging (deep) sources in this order:
+//   1. -f / --file
+//   2. --json
+//   3. dotted-path flags
+// Later sources override earlier ones at the leaf level. Arrays are replaced, not concatenated.
+// Returns undefined if no source is provided.
+export function buildBody(sources: BodySources): unknown {
+  const layers: any[] = [];
+  if (sources.file) layers.push(loadFile(sources.file));
+  if (sources.json) layers.push(parseInlineJson(sources.json));
+  if (sources.fields && Object.keys(sources.fields).length > 0) {
+    const obj: any = {};
+    for (const [path, raw] of Object.entries(sources.fields)) {
+      setDottedPath(obj, path, parseScalar(raw));
+    }
+    layers.push(obj);
+  }
+  if (layers.length === 0) return undefined;
+  return layers.reduce((acc, layer) => deepMerge(acc, layer), {});
+}
+
+function loadFile(path: string): unknown {
+  const text = path === "-" ? fs.readFileSync(0, "utf-8") : fs.readFileSync(path, "utf-8");
+  // js-yaml's safeLoad handles JSON too (JSON is valid YAML). But trim first — empty file is null.
+  const parsed = yaml.load(text);
+  if (parsed === null || parsed === undefined) {
+    throw new Error(`File ${path} parsed as empty`);
+  }
+  return parsed;
+}
+
+function parseInlineJson(s: string): unknown {
+  try {
+    return JSON.parse(s);
+  } catch (e) {
+    throw new Error(`--json value is not valid JSON: ${(e as Error).message}`);
+  }
+}
+
+function isPlainObject(v: unknown): v is Record<string, unknown> {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+
+function deepMerge(target: any, source: any): any {
+  if (!isPlainObject(target) || !isPlainObject(source)) return source;
+  const out: any = { ...target };
+  for (const [k, v] of Object.entries(source)) {
+    if (isPlainObject(v) && isPlainObject(out[k])) {
+      out[k] = deepMerge(out[k], v);
+    } else {
+      out[k] = v;
+    }
+  }
+  return out;
+}