@dbx-tools/shared 0.1.18

package/src/log.ts

@@ -0,0 +1,116 @@
+import type { NameLike } from "./common.js";
+
+/** Plugin-facing logger surface returned by {@link logger}. */
+export interface Logger {
+  debug(message: string, attributes?: Record<string, unknown>): void;
+  info(message: string, attributes?: Record<string, unknown>): void;
+  warn(message: string, attributes?: Record<string, unknown>): void;
+  error(message: string, attributes?: Record<string, unknown>): void;
+}
+
+/**
+ * Severity ordering. A log call below the active threshold is
+ * discarded entirely (no string formatting, no console call). The
+ * threshold is read on every call from `process.env.LOG_LEVEL`,
+ * case-insensitive, defaulting to `info` when unset / empty /
+ * unrecognised. Set `LOG_LEVEL=debug` for verbose dev output,
+ * `LOG_LEVEL=warn` to silence info chatter in production, etc.
+ *
+ * Lazy on purpose: looking up `process.env.LOG_LEVEL` per call
+ * costs nothing meaningful, and it lets test runners (and other
+ * embedders) flip the level after `log.ts` has already been
+ * imported, without restarting the process or reaching into
+ * private state.
+ */
+export type LogLevel = "debug" | "info" | "warn" | "error";
+
+const LEVEL_RANK: Readonly<Record<LogLevel, number>> = {
+  debug: 10,
+  info: 20,
+  warn: 30,
+  error: 40,
+};
+
+const DEFAULT_LEVEL: LogLevel = "info";
+
+/**
+ * Read the active threshold from `process.env.LOG_LEVEL`. Recognises
+ * any case (`DEBUG`, `Debug`, `debug`), trims whitespace, falls back
+ * to {@link DEFAULT_LEVEL} when unset / empty / unrecognised.
+ *
+ * Browser-safe: `process` is undefined in browser bundles unless a
+ * polyfill or build-time replace is set up, so we guard the access.
+ * In a Vite app, set `LOG_LEVEL` via `define` config or just leave
+ * it - the default `info` is sane for production browser code.
+ */
+function activeLevel(): LogLevel {
+  const env = typeof process !== "undefined" ? process.env : undefined;
+  const raw = env?.LOG_LEVEL?.toLowerCase().trim();
+  if (raw && Object.prototype.hasOwnProperty.call(LEVEL_RANK, raw)) {
+    return raw as LogLevel;
+  }
+  return DEFAULT_LEVEL;
+}
+
+/** True when calls at `level` should reach the console. */
+function shouldEmit(level: LogLevel): boolean {
+  return LEVEL_RANK[level] >= LEVEL_RANK[activeLevel()];
+}
+
+const LOGGER_NAME_REGEX = /^(?:[a-z][a-z0-9+.-]*:\/\/)?.*\/([^/.]+)(?:\.[^/]+)?$/i;
+
+function extractLoggerName(
+  loggerName: NameLike | string | undefined,
+): string | undefined {
+  if (!loggerName) return undefined;
+  else if (typeof loggerName === "string") {
+    const match = loggerName.match(LOGGER_NAME_REGEX);
+    return match?.[1] ?? loggerName;
+  } else {
+    return extractLoggerName(loggerName?.name);
+  }
+}
+
+/**
+ * Build a per-plugin logger that writes to `console` with an optional
+ * `[plugin-name]` prefix derived from `plugin.name` or the string you pass in.
+ *
+ * Calls below `process.env.LOG_LEVEL` are discarded before any
+ * string work happens, so leaving `log.debug({...heavy details})`
+ * in production code is free as long as `LOG_LEVEL` is `info` or
+ * higher. Default level is `info`.
+ *
+ * @example
+ * ```ts
+ * import { logUtils } from "@dbx-tools/shared";
+ *
+ * class MyPlugin extends Plugin {
+ *   private log = logUtils.logger(this);
+ *
+ *   override async setup() {
+ *     this.log.info("starting");
+ *     this.log.warn("missing optional config", { reason: "no env var" });
+ *   }
+ * }
+ * ```
+ */
+export function logger(loggerName: NameLike | string | undefined): Logger {
+  const name = extractLoggerName(loggerName);
+  function log(
+    level: LogLevel,
+    consoleFn: (...args: unknown[]) => void,
+    message: string,
+    attributes?: Record<string, unknown>,
+  ): void {
+    if (!shouldEmit(level)) return;
+    const logMessage = name ? `[${name}] ${message}` : message;
+    const logArgs = [logMessage, attributes].filter(Boolean);
+    consoleFn(...logArgs);
+  }
+  return {
+    debug: (msg, attrs) => log("debug", console.debug, msg, attrs),
+    info: (msg, attrs) => log("info", console.info, msg, attrs),
+    warn: (msg, attrs) => log("warn", console.warn, msg, attrs),
+    error: (msg, attrs) => log("error", console.error, msg, attrs),
+  };
+}

package/src/net.browser.ts

@@ -0,0 +1,174 @@
+/**
+ * Browser-safe networking helpers: URL parsing and path joining that
+ * gracefully handle partial inputs. No node-only imports, so this
+ * module is the canonical home for anything URL-shaped that also has
+ * to run in a Vite / Webpack / esbuild client bundle.
+ *
+ * Public API: {@link joinUrl}, {@link parseUrl}. The
+ * single-leading/trailing-slash stripper `stripBoundarySlashes` is
+ * private to this module.
+ *
+ * The server-side `./net.ts` re-exports everything here verbatim and
+ * tacks on its own node-only helpers (e.g. `getRandomPort`), so the
+ * `netUtils` namespace looks identical from both entry points.
+ */
+
+// ────────────────────────────────────────────────────────────────
+// Types
+// ────────────────────────────────────────────────────────────────
+
+/**
+ * One input to {@link joinUrl}: a string, a (recursively nested)
+ * array of segments, or `null` / `undefined` (skipped).
+ *
+ * The recursive shape lets callers compose path fragments without
+ * pre-flattening: `joinUrl("a", ["b", ["c", "d"]])` is valid.
+ *
+ * The array variant uses an interface (rather than a self-referential
+ * type alias) because Bun's TS parser bails on `type X = ... | X[] | ...`
+ * but accepts the equivalent `interface XArr extends Array<X>`.
+ */
+export type UrlSegmentLike = string | UrlSegmentArray | null | undefined;
+export interface UrlSegmentArray extends ReadonlyArray<UrlSegmentLike> {}
+
+/**
+ * Anything {@link parseUrl} knows how to coerce into a `URL`:
+ *
+ * - A WHATWG `URL` instance: returned as-is when no extra path is
+ *   supplied; otherwise re-parsed with the path appended.
+ * - A string: parsed by the `URL` constructor; `https://` is
+ *   auto-prefixed when no scheme is present, so bare hostnames like
+ *   `"example.com"` round-trip into a usable URL.
+ * - Any object with a `url` field of the above shapes (e.g. a fetch
+ *   `Request`, a Databricks `WorkspaceClient` config, etc.).
+ */
+export type UrlLike = URL | string | { url: string };
+
+// ────────────────────────────────────────────────────────────────
+// URL helpers
+// ────────────────────────────────────────────────────────────────
+
+/**
+ * Join URL path segments with `/`, with three pragmatic conveniences
+ * for building URLs piecemeal:
+ *
+ *   1. Nullish or blank segments are dropped, so callers don't have
+ *      to guard around optional path components.
+ *   2. Each string segment has any leading or trailing `/` stripped
+ *      before joining, so `"/api"` + `"v2/"` round-trips to `/api/v2`
+ *      regardless of how the caller terminated each part.
+ *   3. Array segments recurse, with their joined form inlined into
+ *      the outer result.
+ *
+ * The result is prefixed with `/` to make it path-absolute, except
+ * when any segment carries an explicit `://` scheme (e.g.
+ * `"https://x.com"`), in which case the scheme is preserved verbatim.
+ *
+ * Returns `""` when every input was nullish or blank.
+ *
+ * @example
+ * joinUrl("a", "b");                    // "/a/b"
+ * joinUrl("/api/", "/v2/", "x");        // "/api/v2/x"
+ * joinUrl(["a", "b"], "c");             // "/a/b/c"
+ * joinUrl("https://ex.com", "/api/x");  // "https://ex.com/api/x"
+ * joinUrl(null, "", "x", undefined);    // "/x"
+ * joinUrl();                            // ""
+ * joinUrl(null);                        // ""
+ */
+export function joinUrl(...urlSegments: UrlSegmentLike[]): string {
+  const parts: string[] = [];
+  for (const segment of urlSegments) {
+    if (segment == null) continue;
+    if (Array.isArray(segment)) {
+      // Recurse, then strip the inner result's leading `/` so the
+      // outer path-absolute prepend doesn't double up to `//a/b/c`.
+      const inner = joinUrl(...segment);
+      if (inner) parts.push(stripBoundarySlashes(inner));
+      continue;
+    }
+    // `Array.isArray` narrows away the UrlSegmentArray branch but
+    // leaves TS believing `segment` could still be a `string` only,
+    // which it now is - the type cast is just to silence a known
+    // TS limitation around recursive interface narrowing.
+    const trimmed = (segment as string).trim();
+    if (!trimmed) continue;
+    parts.push(stripBoundarySlashes(trimmed));
+  }
+  const joined = parts.filter(Boolean).join("/");
+  if (!joined) return "";
+  return joined.includes("://") ? joined : "/" + joined;
+}
+
+/**
+ * Coerce a {@link UrlLike} input into a parsed `URL`, returning `null`
+ * for anything that cannot be coerced (null/undefined, empty string,
+ * malformed URL, an object whose `url` field doesn't parse).
+ *
+ * Mirrors WHATWG `URL.parse(...)` semantics: parse on success, `null`
+ * on failure - never throws.
+ *
+ * Bare hostnames are upgraded to `https://` before parsing, so callers
+ * can hand in user-provided values like `"workspace.cloud.databricks.com"`
+ * without an explicit scheme.
+ *
+ * Optional trailing `path` arguments are appended via {@link joinUrl}.
+ * When `input` is nullish (or just `"/"` / blank) but a `path` is
+ * provided, the URL is built against `http://localhost`, which is
+ * convenient for tests and for callers that resolve the host later.
+ *
+ * @example
+ * parseUrl("example.com");                        // URL { https://example.com/ }
+ * parseUrl("http://example.com/path");            // URL { http://example.com/path }
+ * parseUrl({ url: "https://api.example" });       // URL { https://api.example/ }
+ * parseUrl("example.com", "/api", "v2", "items"); // URL { https://example.com/api/v2/items }
+ * parseUrl("example.com", ["api", "v2"]);         // URL { https://example.com/api/v2 }
+ * parseUrl(null, "/api/x");                       // URL { http://localhost/api/x }
+ * parseUrl("");                                   // null
+ * parseUrl(null);                                 // null
+ */
+export function parseUrl(
+  input: UrlLike | null | undefined,
+  ...path: UrlSegmentLike[]
+): URL | null {
+  if (typeof input === "string") {
+    input = input.trim();
+    const match = input.match(/^([a-z][a-z0-9+.-]*):\/\/(.*)$/i);
+    const rest = match?.[2] ?? input;
+    if (!rest || rest === "/") return parseUrl(null, ...path);
+    const scheme = match?.[1];
+    if (!scheme) input = `https://${input}`;
+  }
+  const joinedPath = joinUrl(...path);
+  if (input == null) {
+    if (joinedPath) return parseUrl("http://localhost", joinedPath);
+    return null;
+  }
+  if (input instanceof URL) {
+    if (joinedPath) return parseUrl(input.toString(), joinedPath);
+    return input;
+  }
+  if (typeof input === "string") {
+    const candidate = joinUrl(input, joinedPath);
+    if (candidate) {
+      try {
+        return new URL(candidate);
+      } catch {
+        // Fall through to `null`.
+      }
+    }
+    return null;
+  }
+  return parseUrl(input.url, joinedPath);
+}
+
+// ────────────────────────────────────────────────────────────────
+// Private helpers
+// ────────────────────────────────────────────────────────────────
+
+/** Strip a single leading `/` and a single trailing `/`, if present. */
+function stripBoundarySlashes(s: string): string {
+  let out = s;
+  if (out.startsWith("/")) out = out.slice(1);
+  if (out.endsWith("/")) out = out.slice(0, -1);
+  return out;
+}

package/src/net.ts

@@ -0,0 +1,32 @@
+/**
+ * Server-side networking helpers. Re-exports every browser-safe URL
+ * helper from {@link ./net.browser.ts} verbatim and adds node-only
+ * additions (currently {@link getRandomPort}), so the `netUtils`
+ * namespace exposes the same URL surface from either entry point and
+ * picks up node-only helpers automatically on the server.
+ */
+
+import net from "node:net";
+
+export * from "./net.browser.js";
+
+/**
+ * Bind a transient TCP listener on port `0`, read the OS-assigned
+ * port, close the listener, and resolve with the port. Used to grab
+ * a free local port for tests, devloops, and child processes.
+ */
+export async function getRandomPort(): Promise<number> {
+  return await new Promise((resolve, reject) => {
+    const server = net.createServer();
+    server.listen(0, () => {
+      const address = server.address();
+      if (!address || typeof address === "string") {
+        reject(new Error("Failed to get port"));
+        return;
+      }
+      const port = address.port;
+      server.close(() => resolve(port));
+    });
+    server.on("error", reject);
+  });
+}

package/src/project.ts

@@ -0,0 +1,264 @@
+/**
+ * Project introspection helpers shared across AppKit plugins.
+ *
+ * Resolve a human-friendly project name and parse git remote URLs into
+ * repo names. Exposed as `projectUtils.*` from the shared barrel so
+ * naming inside this module drops the redundant `project` prefix:
+ * `projectUtils.name()` instead of `projectName()`, etc.
+ *
+ * **Server-only.** Imports `node:fs`, `node:path`, `node:child_process`,
+ * and `node:util` at module load. Browser bundles must use
+ * `@dbx-tools/shared`'s `index.client.ts` entry point, which
+ * skips this module entirely.
+ */
+
+import { execFile } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { basename, dirname, resolve } from "node:path";
+import { promisify } from "node:util";
+
+const execFileAsync = promisify(execFile);
+
+const nameByCwd = new Map<string, Promise<string>>();
+
+export interface NameOptions {
+  /** Directory to start from. Defaults to `process.cwd()`. */
+  cwd?: string;
+}
+
+interface PackageJson {
+  name?: string;
+  workspaces?: unknown;
+}
+
+/**
+ * Resolve a human-friendly project name for the repo rooted at `cwd`.
+ *
+ * Order:
+ * 1. `name` from the root `package.json` (via `npm pkg get name` when available,
+ *    otherwise read the file after locating the root).
+ * 2. Repository name from `git remote get-url origin`.
+ * 3. Basename of the project root directory.
+ */
+export function name(options?: NameOptions): Promise<string> {
+  const cwd = resolve(options?.cwd ?? process.cwd());
+  let pending = nameByCwd.get(cwd);
+  if (pending === undefined) {
+    pending = resolveProjectName(cwd);
+    nameByCwd.set(cwd, pending);
+  }
+  return pending;
+}
+
+/**
+ * Parse a git remote URL (`https://...`, `git@host:owner/repo.git`, etc.)
+ * and return the repo segment, stripping any `.git` suffix. Returns
+ * `undefined` for empty or unparsable input.
+ */
+export function parseGitRemote(url: string): string | undefined {
+  const trimmed = url.trim();
+  if (!trimmed) {
+    return undefined;
+  }
+
+  const scp = /^[^@]+@[^:]+:(.+)$/i.exec(trimmed);
+  if (scp) {
+    const segment = scp[1];
+    return lastPathSegment(segment ?? "");
+  }
+
+  try {
+    const normalized = trimmed.replace(/\.git$/i, "");
+    const pathname = new URL(normalized).pathname;
+    const segment = pathname.split("/").filter(Boolean).at(-1);
+    return segment ? lastPathSegment(segment) : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+async function resolveProjectName(cwd: string): Promise<string> {
+  const root = await findProjectRoot(cwd);
+
+  const fromPackage = (await readNameViaNpm(root)) ?? readNameFromPackageJson(root);
+  if (fromPackage) {
+    return fromPackage;
+  }
+
+  const fromGit = await readNameFromGitRemote(root);
+  if (fromGit) {
+    return fromGit;
+  }
+
+  return basename(root);
+}
+
+async function findProjectRoot(startDir: string): Promise<string> {
+  const cwd = resolve(startDir);
+
+  const fromNpmWorkspace = await npmWorkspaceRoot(cwd);
+  if (fromNpmWorkspace && hasPackageJson(fromNpmWorkspace)) {
+    return preferWorkspacesRoot(fromNpmWorkspace);
+  }
+
+  const fromNpmPrefix = await npmPrefix(cwd);
+  if (fromNpmPrefix && hasPackageJson(fromNpmPrefix)) {
+    return preferWorkspacesRoot(fromNpmPrefix);
+  }
+
+  const walked = walkUpForPackageRoot(cwd);
+  if (walked) {
+    return walked;
+  }
+
+  const fromGit = await gitTopLevel(cwd);
+  if (fromGit && hasPackageJson(fromGit)) {
+    return fromGit;
+  }
+
+  return cwd;
+}
+
+function preferWorkspacesRoot(startDir: string): string {
+  return walkUpForPackageRoot(startDir) ?? startDir;
+}
+
+function walkUpForPackageRoot(startDir: string): string | undefined {
+  let dir = resolve(startDir);
+  let topmost: string | undefined;
+  let workspacesRoot: string | undefined;
+
+  while (true) {
+    const pkgPath = resolve(dir, "package.json");
+    if (existsSync(pkgPath)) {
+      topmost = dir;
+      const pkg = readPackageJson(pkgPath);
+      if (pkg?.workspaces !== undefined) {
+        workspacesRoot = dir;
+      }
+    }
+
+    const parent = dirname(dir);
+    if (parent === dir) {
+      break;
+    }
+    dir = parent;
+  }
+
+  return workspacesRoot ?? topmost;
+}
+
+function hasPackageJson(dir: string): boolean {
+  return existsSync(resolve(dir, "package.json"));
+}
+
+async function npmPrefix(cwd: string): Promise<string | undefined> {
+  return runNpm(["prefix"], cwd);
+}
+
+async function npmWorkspaceRoot(cwd: string): Promise<string | undefined> {
+  const nodeModules = await runNpm(["root", "-w"], cwd);
+  if (!nodeModules) {
+    return undefined;
+  }
+  return dirname(nodeModules);
+}
+
+async function runNpm(args: string[], cwd: string): Promise<string | undefined> {
+  try {
+    const { stdout } = await execFileAsync("npm", args, {
+      cwd,
+      encoding: "utf8",
+    });
+    const value = stdout.trim();
+    return value || undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+async function readNameViaNpm(root: string): Promise<string | undefined> {
+  try {
+    const { stdout } = await execFileAsync(
+      "npm",
+      ["pkg", "get", "name", "--prefix", root],
+      { encoding: "utf8" },
+    );
+    return parseNpmPkgGetValue(stdout);
+  } catch {
+    return undefined;
+  }
+}
+
+function parseNpmPkgGetValue(stdout: string): string | undefined {
+  const trimmed = stdout.trim();
+  if (!trimmed) {
+    return undefined;
+  }
+  try {
+    const parsed: unknown = JSON.parse(trimmed);
+    if (typeof parsed === "string" && parsed.trim()) {
+      return parsed.trim();
+    }
+  } catch {
+    return trimmed.replace(/^"|"$/g, "").trim() || undefined;
+  }
+  return undefined;
+}
+
+function readNameFromPackageJson(root: string): string | undefined {
+  const pkgPath = resolve(root, "package.json");
+  if (!existsSync(pkgPath)) {
+    return undefined;
+  }
+  const pkg = readPackageJson(pkgPath);
+  const pkgName = pkg?.name?.trim();
+  return pkgName || undefined;
+}
+
+function readPackageJson(path: string): PackageJson | undefined {
+  try {
+    return JSON.parse(readFileSync(path, "utf8")) as PackageJson;
+  } catch {
+    return undefined;
+  }
+}
+
+async function readNameFromGitRemote(root: string): Promise<string | undefined> {
+  const url = await gitRemoteOriginUrl(root);
+  if (!url) {
+    return undefined;
+  }
+  return parseGitRemote(url);
+}
+
+async function gitRemoteOriginUrl(root: string): Promise<string | undefined> {
+  try {
+    const { stdout } = await execFileAsync(
+      "git",
+      ["-C", root, "remote", "get-url", "origin"],
+      { encoding: "utf8" },
+    );
+    return stdout.trim() || undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+async function gitTopLevel(cwd: string): Promise<string | undefined> {
+  try {
+    const { stdout } = await execFileAsync(
+      "git",
+      ["-C", cwd, "rev-parse", "--show-toplevel"],
+      { encoding: "utf8" },
+    );
+    return stdout.trim() || undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+function lastPathSegment(path: string): string {
+  const segment = path.split("/").filter(Boolean).at(-1) ?? path;
+  return segment.replace(/\.git$/i, "");
+}