@dbx-tools/shared 0.1.18

package/dist/src/project.js

@@ -0,0 +1,215 @@
+/**
+ * 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();
+/**
+ * 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) {
+    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) {
+    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) {
+    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) {
+    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) {
+    return walkUpForPackageRoot(startDir) ?? startDir;
+}
+function walkUpForPackageRoot(startDir) {
+    let dir = resolve(startDir);
+    let topmost;
+    let workspacesRoot;
+    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) {
+    return existsSync(resolve(dir, "package.json"));
+}
+async function npmPrefix(cwd) {
+    return runNpm(["prefix"], cwd);
+}
+async function npmWorkspaceRoot(cwd) {
+    const nodeModules = await runNpm(["root", "-w"], cwd);
+    if (!nodeModules) {
+        return undefined;
+    }
+    return dirname(nodeModules);
+}
+async function runNpm(args, cwd) {
+    try {
+        const { stdout } = await execFileAsync("npm", args, {
+            cwd,
+            encoding: "utf8",
+        });
+        const value = stdout.trim();
+        return value || undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+async function readNameViaNpm(root) {
+    try {
+        const { stdout } = await execFileAsync("npm", ["pkg", "get", "name", "--prefix", root], { encoding: "utf8" });
+        return parseNpmPkgGetValue(stdout);
+    }
+    catch {
+        return undefined;
+    }
+}
+function parseNpmPkgGetValue(stdout) {
+    const trimmed = stdout.trim();
+    if (!trimmed) {
+        return undefined;
+    }
+    try {
+        const parsed = JSON.parse(trimmed);
+        if (typeof parsed === "string" && parsed.trim()) {
+            return parsed.trim();
+        }
+    }
+    catch {
+        return trimmed.replace(/^"|"$/g, "").trim() || undefined;
+    }
+    return undefined;
+}
+function readNameFromPackageJson(root) {
+    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) {
+    try {
+        return JSON.parse(readFileSync(path, "utf8"));
+    }
+    catch {
+        return undefined;
+    }
+}
+async function readNameFromGitRemote(root) {
+    const url = await gitRemoteOriginUrl(root);
+    if (!url) {
+        return undefined;
+    }
+    return parseGitRemote(url);
+}
+async function gitRemoteOriginUrl(root) {
+    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) {
+    try {
+        const { stdout } = await execFileAsync("git", ["-C", cwd, "rev-parse", "--show-toplevel"], { encoding: "utf8" });
+        return stdout.trim() || undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function lastPathSegment(path) {
+    const segment = path.split("/").filter(Boolean).at(-1) ?? path;
+    return segment.replace(/\.git$/i, "");
+}

package/dist/src/string.d.ts

@@ -0,0 +1,105 @@
+type TokenizeOptions = {
+    distinct?: boolean;
+    lowerCase?: boolean;
+    capitalize?: boolean;
+    omitUriScheme?: boolean;
+    omitEmailDomain?: boolean;
+    camelCase?: boolean;
+};
+type KeyOptions = Omit<TokenizeOptions, "lowerCase" | "capitalize"> & {
+    maxLength?: number;
+    truncateStrategy?: "hash" | "trim" | "empty";
+    truncateHashLength?: number;
+};
+type IdentifierOptions = KeyOptions & {
+    delimiter?: string;
+};
+export declare function tokenizeWithOptions(options: TokenizeOptions, ...values: unknown[]): Generator<string>;
+export declare function tokenize(...values: unknown[]): Generator<string>;
+/**
+ * Join tokenized values with `delimiter`. When the next token would push the
+ * result over `maxLength`: `trim` stops adding; `empty` returns `""`; `hash`
+ * appends a digest of accepted tokens plus the overflow token if the result
+ * still fits, otherwise `""`.
+ */
+export declare function toIdentifierWithOptions(options: IdentifierOptions, ...values: unknown[]): string;
+export declare function toIdentifier(...values: unknown[]): string;
+/**
+ * Slugified identifier: same rules as {@link toIdentifierWithOptions} with the
+ * delimiter forced to `-`. Accepts {@link KeyOptions} so callers cannot
+ * override the delimiter.
+ */
+export declare function toSlugWithOptions(options: KeyOptions, ...values: unknown[]): string;
+export declare function toSlug(...values: unknown[]): string;
+/**
+ * Trim `value` and return `null` for non-strings, `undefined`, or
+ * strings that are empty after trimming. Lets call sites collapse the
+ * common
+ *
+ * ```ts
+ * typeof v === "string" && v.trim() ? v.trim() : null
+ * ```
+ *
+ * dance into a single helper. Useful for HTTP header / query / form
+ * extractors where downstream code wants `string | null` to drive a
+ * cheap `??` / `if (x)` cascade.
+ */
+export declare function trimToNull(value: unknown): string | null;
+/**
+ * Trim the first usable string out of `value`. Returns `null` when
+ * `value` is `undefined`, `null`, an empty string, or an array whose
+ * first string member is empty. Mirrors how Express / Node header
+ * accessors expose single vs. repeated headers - the first
+ * non-empty entry wins, everything else is ignored.
+ */
+export declare function firstNonEmpty(value: unknown): string | null;
+/**
+ * Tagged-template helper that collapses a multi-line indented
+ * template literal into a single space-joined string. Lets call
+ * sites write Zod `.describe()` blocks, Mastra tool descriptions,
+ * and other long prose constants as readable indented paragraphs
+ * in source while still emitting clean text the LLM (or any other
+ * consumer) doesn't have to mentally re-flow. Interpolated values
+ * are stringified verbatim and folded with the surrounding
+ * whitespace.
+ *
+ * ```ts
+ * toDescription`
+ *   Ask the Genie space "${alias}" a question.
+ *   Pass the answer through as-is.
+ * `;
+ * // -> 'Ask the Genie space "default" a question. Pass the answer through as-is.'
+ * ```
+ */
+export declare function toDescription(strings: TemplateStringsArray, ...values: unknown[]): string;
+/**
+ * Slugify `value` (using the standard {@link toIdentifierWithOptions}
+ * tokenizer + delimiter rules) and **always** suffix a short
+ * deterministic hash. Use when you need a stable, slugified id that
+ * is guaranteed to be unique across descriptions sharing the same
+ * leading tokens (tool ids, cache keys, etc.).
+ *
+ * Behaviour differs from `toIdentifierWithOptions({ maxLength,
+ * truncateStrategy: "hash" })`: that helper only appends a hash when
+ * the slug *overflows* `maxLength`. This helper appends a hash
+ * unconditionally so the result is collision-resistant even for
+ * short inputs. The hash is computed over the raw `value` so two
+ * descriptions producing the same slug still get different ids.
+ *
+ * @param value - Source string (typically a tool/agent description).
+ * @param options.delimiter - Token separator (default `"_"`).
+ * @param options.slugMaxLength - Cap on the slug portion (the part
+ *   before the hash). Default 32.
+ * @param options.hashLength - Length of the suffix produced by
+ *   `commonUtils.fnvHash` (Crockford-style base-32 alphabet, max 7
+ *   chars). Default 6.
+ * @param options.fallbackPrefix - Prefix used when the slug is empty
+ *   (e.g. punctuation-only input). Default `"id"`.
+ */
+export declare function toUniqueSlug(value: string, options?: {
+    delimiter?: string;
+    slugMaxLength?: number;
+    hashLength?: number;
+    fallbackPrefix?: string;
+}): string;
+export {};

package/dist/src/string.js

@@ -0,0 +1,220 @@
+// Direct import (not via the barrel) to avoid a self-import cycle:
+// `index.client.ts` re-exports `* as stringUtils from "./src/string.js"`,
+// so going back through it would close a loop.
+import { fnvHash, fnvHashWithOptions } from "./common.js";
+const TOKENIZE_CAMEL_CASE_REGEXP = /[A-Z]?[a-z]+|[0-9]+|[A-Z]+(?![a-z])/g;
+const TOKENIZE_NON_ALPHANUMERIC_REGEXP = /[a-zA-Z0-9]+/g;
+const URI_REGEXP = /^([a-zA-Z][a-zA-Z0-9+.-]*)?:\/\/([^\s/?#][^\s]*)?$/;
+const EMAIL_REGEXP = /^([a-zA-Z0-9.!#$%&'*+/=?^_`{|}~-]+)@([a-zA-Z0-9-]+(?:\.[a-zA-Z0-9-]+)+)$/;
+const TOKENIZE_DEFAULTS = {
+    distinct: false,
+    lowerCase: false,
+    capitalize: false,
+    omitUriScheme: false,
+    omitEmailDomain: false,
+    camelCase: true,
+};
+const IDENTIFIER_DEFAULTS = {
+    ...TOKENIZE_DEFAULTS,
+    lowerCase: true,
+    maxLength: Infinity,
+    truncateStrategy: "hash",
+    truncateHashLength: 6,
+    delimiter: "-",
+};
+export function* tokenizeWithOptions(options, ...values) {
+    const opts = { ...TOKENIZE_DEFAULTS, ...options };
+    const seen = opts.distinct ? new Set() : undefined;
+    const regexp = opts.camelCase
+        ? TOKENIZE_CAMEL_CASE_REGEXP
+        : TOKENIZE_NON_ALPHANUMERIC_REGEXP;
+    for (const value of values) {
+        if (value == null)
+            continue;
+        let stringValue = typeof value === "string" ? value : String(value);
+        if (!stringValue)
+            continue;
+        if (opts.omitUriScheme) {
+            const match = stringValue.match(URI_REGEXP);
+            if (match)
+                stringValue = match[2] ?? "";
+        }
+        if (opts.omitEmailDomain) {
+            const match = stringValue.match(EMAIL_REGEXP);
+            if (match)
+                stringValue = match[1] ?? "";
+        }
+        if (!stringValue)
+            continue;
+        for (const tokenMatch of stringValue.matchAll(regexp)) {
+            let token = tokenMatch[0];
+            if (opts.lowerCase)
+                token = token.toLowerCase();
+            if (opts.capitalize)
+                token = token.charAt(0).toUpperCase() + token.slice(1);
+            if (!token || seen?.has(token))
+                continue;
+            seen?.add(token);
+            yield token;
+        }
+    }
+}
+export function* tokenize(...values) {
+    yield* tokenizeWithOptions({}, ...values);
+}
+/**
+ * Join tokenized values with `delimiter`. When the next token would push the
+ * result over `maxLength`: `trim` stops adding; `empty` returns `""`; `hash`
+ * appends a digest of accepted tokens plus the overflow token if the result
+ * still fits, otherwise `""`.
+ */
+export function toIdentifierWithOptions(options, ...values) {
+    const opts = {
+        ...IDENTIFIER_DEFAULTS,
+        ...options,
+        lowerCase: true,
+    };
+    const tokens = [];
+    let currentLength = 0;
+    for (const token of tokenizeWithOptions(opts, ...values)) {
+        const sepLength = tokens.length > 0 ? opts.delimiter.length : 0;
+        const nextLength = currentLength + sepLength + token.length;
+        if (nextLength > opts.maxLength) {
+            if (opts.truncateStrategy === "empty")
+                return "";
+            if (opts.truncateStrategy === "trim")
+                break;
+            const hash = digestTokens(opts.truncateHashLength, tokens, token);
+            if (currentLength + sepLength + hash.length <= opts.maxLength) {
+                return tokens.length > 0
+                    ? tokens.join(opts.delimiter) + opts.delimiter + hash
+                    : hash;
+            }
+            return "";
+        }
+        tokens.push(token);
+        currentLength = nextLength;
+    }
+    return tokens.join(opts.delimiter);
+}
+export function toIdentifier(...values) {
+    return toIdentifierWithOptions({}, ...values);
+}
+/**
+ * Slugified identifier: same rules as {@link toIdentifierWithOptions} with the
+ * delimiter forced to `-`. Accepts {@link KeyOptions} so callers cannot
+ * override the delimiter.
+ */
+export function toSlugWithOptions(options, ...values) {
+    return toIdentifierWithOptions({ ...options, delimiter: "-" }, ...values);
+}
+export function toSlug(...values) {
+    return toSlugWithOptions({}, ...values);
+}
+/**
+ * Trim `value` and return `null` for non-strings, `undefined`, or
+ * strings that are empty after trimming. Lets call sites collapse the
+ * common
+ *
+ * ```ts
+ * typeof v === "string" && v.trim() ? v.trim() : null
+ * ```
+ *
+ * dance into a single helper. Useful for HTTP header / query / form
+ * extractors where downstream code wants `string | null` to drive a
+ * cheap `??` / `if (x)` cascade.
+ */
+export function trimToNull(value) {
+    if (typeof value !== "string")
+        return null;
+    const trimmed = value.trim();
+    return trimmed ? trimmed : null;
+}
+/**
+ * Trim the first usable string out of `value`. Returns `null` when
+ * `value` is `undefined`, `null`, an empty string, or an array whose
+ * first string member is empty. Mirrors how Express / Node header
+ * accessors expose single vs. repeated headers - the first
+ * non-empty entry wins, everything else is ignored.
+ */
+export function firstNonEmpty(value) {
+    if (Array.isArray(value)) {
+        for (const item of value) {
+            const trimmed = trimToNull(item);
+            if (trimmed)
+                return trimmed;
+        }
+        return null;
+    }
+    return trimToNull(value);
+}
+/**
+ * Tagged-template helper that collapses a multi-line indented
+ * template literal into a single space-joined string. Lets call
+ * sites write Zod `.describe()` blocks, Mastra tool descriptions,
+ * and other long prose constants as readable indented paragraphs
+ * in source while still emitting clean text the LLM (or any other
+ * consumer) doesn't have to mentally re-flow. Interpolated values
+ * are stringified verbatim and folded with the surrounding
+ * whitespace.
+ *
+ * ```ts
+ * toDescription`
+ *   Ask the Genie space "${alias}" a question.
+ *   Pass the answer through as-is.
+ * `;
+ * // -> 'Ask the Genie space "default" a question. Pass the answer through as-is.'
+ * ```
+ */
+export function toDescription(strings, ...values) {
+    let out = "";
+    for (let i = 0; i < strings.length; i += 1) {
+        out += strings[i];
+        if (i < values.length)
+            out += String(values[i]);
+    }
+    return out.replace(/\s+/g, " ").trim();
+}
+/**
+ * Slugify `value` (using the standard {@link toIdentifierWithOptions}
+ * tokenizer + delimiter rules) and **always** suffix a short
+ * deterministic hash. Use when you need a stable, slugified id that
+ * is guaranteed to be unique across descriptions sharing the same
+ * leading tokens (tool ids, cache keys, etc.).
+ *
+ * Behaviour differs from `toIdentifierWithOptions({ maxLength,
+ * truncateStrategy: "hash" })`: that helper only appends a hash when
+ * the slug *overflows* `maxLength`. This helper appends a hash
+ * unconditionally so the result is collision-resistant even for
+ * short inputs. The hash is computed over the raw `value` so two
+ * descriptions producing the same slug still get different ids.
+ *
+ * @param value - Source string (typically a tool/agent description).
+ * @param options.delimiter - Token separator (default `"_"`).
+ * @param options.slugMaxLength - Cap on the slug portion (the part
+ *   before the hash). Default 32.
+ * @param options.hashLength - Length of the suffix produced by
+ *   `commonUtils.fnvHash` (Crockford-style base-32 alphabet, max 7
+ *   chars). Default 6.
+ * @param options.fallbackPrefix - Prefix used when the slug is empty
+ *   (e.g. punctuation-only input). Default `"id"`.
+ */
+export function toUniqueSlug(value, options = {}) {
+    const delimiter = options.delimiter ?? "_";
+    const slugMaxLength = options.slugMaxLength ?? 32;
+    const hashLength = options.hashLength ?? 6;
+    const fallbackPrefix = options.fallbackPrefix ?? "id";
+    const slug = toIdentifierWithOptions({ delimiter, maxLength: slugMaxLength, truncateStrategy: "trim" }, value);
+    const suffix = fnvHashWithOptions({ length: hashLength }, value);
+    return slug
+        ? `${slug}${delimiter}${suffix}`
+        : `${fallbackPrefix}${delimiter}${suffix}`;
+}
+function digestTokens(length, parts, extra) {
+    let combined = "";
+    for (const part of parts)
+        combined += part + "\0";
+    if (extra !== undefined)
+        combined += extra + "\0";
+    return fnvHashWithOptions({ length }, combined);
+}