@dbx-tools/shared 0.1.18

package/dist/src/http.js

@@ -0,0 +1,166 @@
+/**
+ * HTTP header helpers shared across AppKit plugins: framework
+ * agnostic readers for HTTP headers and cookies that work uniformly
+ * across Express, Node `IncomingMessage`, WHATWG `Request` / `Response`
+ * / `Headers`, Hono, and any object that exposes a `headers` field of
+ * one of those shapes.
+ *
+ * Public API: {@link forEachHeaderValue}, {@link parseCookies}.
+ * Everything else (the header guards `isHeaders` / `isWrapped` /
+ * `unwrap`, the single cookie-header parser `parseCookieString`) is
+ * private to this module.
+ *
+ * URL parsing and path joining moved to `netUtils` (`./net.browser.ts`)
+ * so the URL surface lives next to the rest of the browser-safe
+ * networking helpers. The Databricks-aware REST helper that used to
+ * live here moved to `apiUtils.fetchApi` (`./api.ts`) so this module
+ * can stay dependency-free and browser-safe.
+ */
+// ────────────────────────────────────────────────────────────────
+// Header helpers
+// ────────────────────────────────────────────────────────────────
+/**
+ * Invokes `consumer` once per value for `headerName`, case-insensitive.
+ *
+ * - **Record input:** if the field is an array (e.g. repeated `Set-Cookie`),
+ *   `consumer` runs once per array item.
+ * - **`Headers` input:** uses `get(name)` (which spec-joins repeats with
+ *   `, `) except for `Set-Cookie`, which uses `getSetCookie()` so each
+ *   cookie is delivered separately.
+ *
+ * @example
+ * forEachHeaderValue(req, "x-trace-id", (v) => spans.push(v));     // Express
+ * forEachHeaderValue(c.req.raw, "set-cookie", (v) => log(v));      // Hono
+ * forEachHeaderValue(headersInstance, "cookie", parse);            // fetch
+ */
+export function forEachHeaderValue(input, headerName, consumer) {
+    const headers = unwrap(input);
+    if (!headers)
+        return;
+    const target = headerName.toLowerCase();
+    if (isHeaders(headers)) {
+        // `Headers.get` joins repeated values with `, ` per spec, which
+        // mangles `Set-Cookie` (cookies legitimately contain commas in
+        // their `expires=` attribute). `getSetCookie` is the dedicated
+        // splitter and is the only safe path for that header.
+        if (target === "set-cookie") {
+            for (const value of headers.getSetCookie())
+                consumer(value);
+            return;
+        }
+        const value = headers.get(headerName);
+        if (value !== null)
+            consumer(value);
+        return;
+    }
+    for (const [key, value] of Object.entries(headers)) {
+        if (value == null || key.toLowerCase() !== target)
+            continue;
+        if (Array.isArray(value)) {
+            for (const item of value)
+                consumer(item);
+        }
+        else {
+            consumer(value);
+        }
+    }
+}
+/**
+ * Parses `Cookie` header values into a name-to-value map (URI-decoded).
+ *
+ * Accepts:
+ *
+ * - A raw `Cookie` string (`"a=1; b=2"`).
+ * - An array of such strings (e.g. multiple `Cookie` headers).
+ * - Any {@link HeaderLike}: a WHATWG `Headers` instance, a header
+ *   record, or a request-like object with a `headers` field.
+ *
+ * First occurrence of each cookie name wins; later duplicates are ignored.
+ *
+ * @example
+ * parseCookies("session=abc; theme=dark");
+ * // { session: "abc", theme: "dark" }
+ *
+ * parseCookies(req);              // Express / Node
+ * parseCookies(c.req.raw);        // Hono
+ * parseCookies(request);          // fetch Request
+ * parseCookies(request.headers);  // WHATWG Headers directly
+ */
+export function parseCookies(input) {
+    if (input == null)
+        return {};
+    const out = {};
+    if (typeof input === "string") {
+        parseCookieString(input, out);
+        return out;
+    }
+    if (Array.isArray(input)) {
+        for (const item of input) {
+            if (typeof item === "string")
+                parseCookieString(item, out);
+        }
+        return out;
+    }
+    forEachHeaderValue(input, "cookie", (value) => {
+        parseCookieString(value, out);
+    });
+    return out;
+}
+// ────────────────────────────────────────────────────────────────
+// Private helpers
+// ────────────────────────────────────────────────────────────────
+/**
+ * Type guard for WHATWG `Headers`. Duck-types on the two methods that
+ * matter to this module (`get` and `getSetCookie`) so polyfilled
+ * implementations and Hono's `HonoHeaders` are accepted without
+ * pulling `Headers` in as a hard dependency.
+ */
+function isHeaders(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        typeof value.get === "function" &&
+        typeof value.getSetCookie === "function");
+}
+/**
+ * `HeaderRecord` is an index signature, so `"headers" in input` cannot
+ * discriminate it from the wrapped `{ headers }` shape at the type
+ * level. This guard inspects the runtime value of `headers`: only
+ * objects (`Headers` or a nested record) qualify as the wrapper shape,
+ * never stray string/array values that happen to live under a `headers`
+ * key on a header record.
+ */
+function isWrapped(input) {
+    const headers = input.headers;
+    return headers != null && typeof headers === "object" && !Array.isArray(headers);
+}
+/**
+ * Parse a single `Cookie`-style header string (`"a=1; b=2"`) into
+ * `out`. Names without a value are skipped; first occurrence wins so
+ * later duplicates are ignored. Cookie values are URI-decoded.
+ */
+function parseCookieString(input, out) {
+    for (const part of input.split(";")) {
+        const eq = part.indexOf("=");
+        if (eq < 0)
+            continue;
+        const name = part.slice(0, eq).trim();
+        if (!name || name in out)
+            continue;
+        const raw = part.slice(eq + 1).trim();
+        out[name] = decodeURIComponent(raw);
+    }
+}
+/**
+ * Normalize a {@link HeaderLike} input down to either a `Headers`
+ * instance or a header `Record`. Returns `null` for missing input so
+ * callers can short-circuit without a separate nullish check.
+ */
+function unwrap(input) {
+    if (input == null)
+        return null;
+    if (isHeaders(input))
+        return input;
+    if (isWrapped(input))
+        return input.headers;
+    return input;
+}

package/dist/src/log.d.ts

@@ -0,0 +1,47 @@
+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";
+/**
+ * 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 declare function logger(loggerName: NameLike | string | undefined): Logger;

package/dist/src/log.js

@@ -0,0 +1,80 @@
+const LEVEL_RANK = {
+    debug: 10,
+    info: 20,
+    warn: 30,
+    error: 40,
+};
+const DEFAULT_LEVEL = "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() {
+    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;
+    }
+    return DEFAULT_LEVEL;
+}
+/** True when calls at `level` should reach the console. */
+function shouldEmit(level) {
+    return LEVEL_RANK[level] >= LEVEL_RANK[activeLevel()];
+}
+const LOGGER_NAME_REGEX = /^(?:[a-z][a-z0-9+.-]*:\/\/)?.*\/([^/.]+)(?:\.[^/]+)?$/i;
+function extractLoggerName(loggerName) {
+    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) {
+    const name = extractLoggerName(loggerName);
+    function log(level, consoleFn, message, attributes) {
+        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/dist/src/net.browser.d.ts

@@ -0,0 +1,98 @@
+/**
+ * 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.
+ */
+/**
+ * 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;
+};
+/**
+ * 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 declare function joinUrl(...urlSegments: UrlSegmentLike[]): string;
+/**
+ * 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 declare function parseUrl(input: UrlLike | null | undefined, ...path: UrlSegmentLike[]): URL | null;

package/dist/src/net.browser.js

@@ -0,0 +1,146 @@
+/**
+ * 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.
+ */
+// ────────────────────────────────────────────────────────────────
+// 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) {
+    const parts = [];
+    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.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, ...path) {
+    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) {
+    let out = s;
+    if (out.startsWith("/"))
+        out = out.slice(1);
+    if (out.endsWith("/"))
+        out = out.slice(0, -1);
+    return out;
+}

package/dist/src/net.d.ts

@@ -0,0 +1,14 @@
+/**
+ * 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.
+ */
+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 declare function getRandomPort(): Promise<number>;

package/dist/src/net.js

@@ -0,0 +1,29 @@
+/**
+ * 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() {
+    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/dist/src/project.d.ts

@@ -0,0 +1,33 @@
+/**
+ * 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.
+ */
+export interface NameOptions {
+    /** Directory to start from. Defaults to `process.cwd()`. */
+    cwd?: string;
+}
+/**
+ * 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 declare function name(options?: NameOptions): Promise<string>;
+/**
+ * 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 declare function parseGitRemote(url: string): string | undefined;