@dbx-tools/core 0.3.43 → 0.4.0

package/lib/index.d.ts

@@ -0,0 +1,11 @@
+export * as brand from "./src/brand.js";
+export * as exec from "./src/exec.js";
+export * as file from "./src/file.js";
+export * as project from "./src/project.js";
+export { BrandContextSchema, defaultBrandContext, parseBrandContext, brandContextJsonSchema, brandContextPrompt, findBrandContextFile, loadBrandContextFile, loadBrandContext, resolveBrandAssetPath } from "./src/brand.js";
+export type { BrandContext, BrandContextInput } from "./src/brand.js";
+export { spawn, spawnSync, shlex } from "./src/exec.js";
+export type { ExecStdio, LineHandler, StdioOption, ExecResult, ExecOptions, SyncExecStdio, SyncExecOptions, SpawnArgs } from "./src/exec.js";
+export { statSync } from "./src/file.js";
+export { root, parseGitRemote, resolveProjectRoots, name, repositoryUrl, npmRegistry } from "./src/project.js";
+export type { ProjectContext } from "./src/project.js";

package/lib/index.js

@@ -0,0 +1,12 @@
+// 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 brand from "./src/brand.js";
+export * as exec from "./src/exec.js";
+export * as file from "./src/file.js";
+export * as project from "./src/project.js";
+export { BrandContextSchema, defaultBrandContext, parseBrandContext, brandContextJsonSchema, brandContextPrompt, findBrandContextFile, loadBrandContextFile, loadBrandContext, resolveBrandAssetPath } from "./src/brand.js";
+export { spawn, spawnSync, shlex } from "./src/exec.js";
+export { statSync } from "./src/file.js";
+export { root, parseGitRemote, resolveProjectRoots, name, repositoryUrl, npmRegistry } from "./src/project.js";
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi9pbmRleC50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSwyQ0FBMkM7QUFDM0MsbURBQW1EO0FBQ25ELHdFQUF3RTtBQUV4RSxPQUFPLEtBQUssS0FBSyxNQUFNLGFBQWEsQ0FBQztBQUNyQyxPQUFPLEtBQUssSUFBSSxNQUFNLFlBQVksQ0FBQztBQUNuQyxPQUFPLEtBQUssSUFBSSxNQUFNLFlBQVksQ0FBQztBQUNuQyxPQUFPLEtBQUssT0FBTyxNQUFNLGVBQWUsQ0FBQztBQUN6QyxPQUFPLEVBQUUsa0JBQWtCLEVBQUUsbUJBQW1CLEVBQUUsaUJBQWlCLEVBQUUsc0JBQXNCLEVBQUUsa0JBQWtCLEVBQUUsb0JBQW9CLEVBQUUsb0JBQW9CLEVBQUUsZ0JBQWdCLEVBQUUscUJBQXFCLEVBQUUsTUFBTSxhQUFhLENBQUM7QUFFMU4sT0FBTyxFQUFFLEtBQUssRUFBRSxTQUFTLEVBQUUsS0FBSyxFQUFFLE1BQU0sWUFBWSxDQUFDO0FBRXJELE9BQU8sRUFBRSxRQUFRLEVBQUUsTUFBTSxZQUFZLENBQUM7QUFDdEMsT0FBTyxFQUFFLElBQUksRUFBRSxjQUFjLEVBQUUsbUJBQW1CLEVBQUUsSUFBSSxFQUFFLGFBQWEsRUFBRSxXQUFXLEVBQUUsTUFBTSxlQUFlLENBQUMiLCJzb3VyY2VzQ29udGVudCI6WyIvLyBHRU5FUkFURUQgYnkgcHJvamVuIHdhdGNoIC0gRE8gTk9UIEVESVQuXG4vLyBSZWdlbmVyYXRlZCBmcm9tIHRoZSBleHBvcnRpbmcgbW9kdWxlcyBpbiAuL3NyYy5cbi8vIEhhbmQgZWRpdHMgYXJlIG92ZXJ3cml0dGVuIG9uIHRoZSBuZXh0IHdhdGNoOyB0aGlzIGZpbGUgaXMgcmVhZC1vbmx5LlxuXG5leHBvcnQgKiBhcyBicmFuZCBmcm9tIFwiLi9zcmMvYnJhbmRcIjtcbmV4cG9ydCAqIGFzIGV4ZWMgZnJvbSBcIi4vc3JjL2V4ZWNcIjtcbmV4cG9ydCAqIGFzIGZpbGUgZnJvbSBcIi4vc3JjL2ZpbGVcIjtcbmV4cG9ydCAqIGFzIHByb2plY3QgZnJvbSBcIi4vc3JjL3Byb2plY3RcIjtcbmV4cG9ydCB7IEJyYW5kQ29udGV4dFNjaGVtYSwgZGVmYXVsdEJyYW5kQ29udGV4dCwgcGFyc2VCcmFuZENvbnRleHQsIGJyYW5kQ29udGV4dEpzb25TY2hlbWEsIGJyYW5kQ29udGV4dFByb21wdCwgZmluZEJyYW5kQ29udGV4dEZpbGUsIGxvYWRCcmFuZENvbnRleHRGaWxlLCBsb2FkQnJhbmRDb250ZXh0LCByZXNvbHZlQnJhbmRBc3NldFBhdGggfSBmcm9tIFwiLi9zcmMvYnJhbmRcIjtcbmV4cG9ydCB0eXBlIHsgQnJhbmRDb250ZXh0LCBCcmFuZENvbnRleHRJbnB1dCB9IGZyb20gXCIuL3NyYy9icmFuZFwiO1xuZXhwb3J0IHsgc3Bhd24sIHNwYXduU3luYywgc2hsZXggfSBmcm9tIFwiLi9zcmMvZXhlY1wiO1xuZXhwb3J0IHR5cGUgeyBFeGVjU3RkaW8sIExpbmVIYW5kbGVyLCBTdGRpb09wdGlvbiwgRXhlY1Jlc3VsdCwgRXhlY09wdGlvbnMsIFN5bmNFeGVjU3RkaW8sIFN5bmNFeGVjT3B0aW9ucywgU3Bhd25BcmdzIH0gZnJvbSBcIi4vc3JjL2V4ZWNcIjtcbmV4cG9ydCB7IHN0YXRTeW5jIH0gZnJvbSBcIi4vc3JjL2ZpbGVcIjtcbmV4cG9ydCB7IHJvb3QsIHBhcnNlR2l0UmVtb3RlLCByZXNvbHZlUHJvamVjdFJvb3RzLCBuYW1lLCByZXBvc2l0b3J5VXJsLCBucG1SZWdpc3RyeSB9IGZyb20gXCIuL3NyYy9wcm9qZWN0XCI7XG5leHBvcnQgdHlwZSB7IFByb2plY3RDb250ZXh0IH0gZnJvbSBcIi4vc3JjL3Byb2plY3RcIjtcbiJdfQ==

package/lib/src/brand.d.ts

@@ -0,0 +1,105 @@
+import { brand as sharedBrand } from "@dbx-tools/shared-core";
+export type BrandContext = sharedBrand.BrandContext;
+export type BrandContextInput = sharedBrand.BrandContextInput;
+export declare const BrandContextSchema: import("zod").ZodObject<{
+    schemaVersion: import("zod").ZodDefault<import("zod").ZodLiteral<"1">>;
+    name: import("zod").ZodDefault<import("zod").ZodString>;
+    shortName: import("zod").ZodDefault<import("zod").ZodString>;
+    tagline: import("zod").ZodDefault<import("zod").ZodString>;
+    description: import("zod").ZodDefault<import("zod").ZodString>;
+    assets: import("zod").ZodDefault<import("zod").ZodObject<{
+        icon: import("zod").ZodDefault<import("zod").ZodObject<{
+            light: import("zod").ZodString;
+            dark: import("zod").ZodOptional<import("zod").ZodString>;
+        }, import("zod/v4/core").$strict>>;
+        logo: import("zod").ZodDefault<import("zod").ZodObject<{
+            light: import("zod").ZodString;
+            dark: import("zod").ZodOptional<import("zod").ZodString>;
+        }, import("zod/v4/core").$strict>>;
+        favicon: import("zod").ZodDefault<import("zod").ZodString>;
+    }, import("zod/v4/core").$strict>>;
+    colors: import("zod").ZodPrefault<import("zod").ZodObject<{
+        primary: import("zod").ZodDefault<import("zod").ZodString>;
+        primaryHover: import("zod").ZodDefault<import("zod").ZodString>;
+        accent: import("zod").ZodDefault<import("zod").ZodString>;
+        foreground: import("zod").ZodDefault<import("zod").ZodString>;
+        background: import("zod").ZodDefault<import("zod").ZodString>;
+        surface: import("zod").ZodDefault<import("zod").ZodString>;
+        muted: import("zod").ZodDefault<import("zod").ZodString>;
+        border: import("zod").ZodDefault<import("zod").ZodString>;
+    }, import("zod/v4/core").$strict>>;
+    typography: import("zod").ZodPrefault<import("zod").ZodObject<{
+        sans: import("zod").ZodDefault<import("zod").ZodString>;
+        mono: import("zod").ZodDefault<import("zod").ZodString>;
+    }, import("zod/v4/core").$strict>>;
+    voice: import("zod").ZodPrefault<import("zod").ZodObject<{
+        audience: import("zod").ZodDefault<import("zod").ZodArray<import("zod").ZodString>>;
+        tone: import("zod").ZodDefault<import("zod").ZodArray<import("zod").ZodString>>;
+        principles: import("zod").ZodDefault<import("zod").ZodArray<import("zod").ZodString>>;
+        avoid: import("zod").ZodDefault<import("zod").ZodArray<import("zod").ZodString>>;
+    }, import("zod/v4/core").$strict>>;
+    links: import("zod").ZodDefault<import("zod").ZodObject<{
+        website: import("zod").ZodOptional<import("zod").ZodString>;
+        repository: import("zod").ZodOptional<import("zod").ZodString>;
+        documentation: import("zod").ZodOptional<import("zod").ZodString>;
+    }, import("zod/v4/core").$strict>>;
+    extensions: import("zod").ZodDefault<import("zod").ZodRecord<import("zod").ZodString, import("zod").ZodUnknown>>;
+}, import("zod/v4/core").$strict>;
+export declare const defaultBrandContext: {
+    schemaVersion: "1";
+    name: string;
+    shortName: string;
+    tagline: string;
+    description: string;
+    assets: {
+        icon: {
+            light: string;
+            dark?: string | undefined;
+        };
+        logo: {
+            light: string;
+            dark?: string | undefined;
+        };
+        favicon: string;
+    };
+    colors: {
+        primary: string;
+        primaryHover: string;
+        accent: string;
+        foreground: string;
+        background: string;
+        surface: string;
+        muted: string;
+        border: string;
+    };
+    typography: {
+        sans: string;
+        mono: string;
+    };
+    voice: {
+        audience: string[];
+        tone: string[];
+        principles: string[];
+        avoid: string[];
+    };
+    links: {
+        website?: string | undefined;
+        repository?: string | undefined;
+        documentation?: string | undefined;
+    };
+    extensions: Record<string, unknown>;
+};
+export declare const parseBrandContext: typeof sharedBrand.parseBrandContext;
+export declare const brandContextJsonSchema: typeof sharedBrand.brandContextJsonSchema;
+export declare const brandContextPrompt: typeof sharedBrand.brandContextPrompt;
+/** Find a conventional YAML or JSON brand file from known project roots. */
+export declare function findBrandContextFile(cwd?: string): string | undefined;
+/** Read and validate one `.yaml`, `.yml`, or `.json` brand context file. */
+export declare function loadBrandContextFile(path: string): Promise<BrandContext>;
+/**
+ * Discover and load a brand context. Missing files resolve to dbx tools defaults;
+ * malformed files fail with their parser or Zod validation error.
+ */
+export declare function loadBrandContext(cwd?: string): Promise<BrandContext>;
+/** Resolve a relative asset reference against the brand file that declared it. */
+export declare function resolveBrandAssetPath(brandFile: string, asset: string): string;

package/lib/src/brand.js

@@ -0,0 +1,66 @@
+/** Node-only discovery and file loading for the shared brand context. */
+import { readFile } from "node:fs/promises";
+import { dirname, extname, isAbsolute, resolve } from "node:path";
+import { brand as sharedBrand } from "@dbx-tools/shared-core";
+import { statSync } from "./file.js";
+import { resolveProjectRoots } from "./project.js";
+const BRAND_CONTEXT_FILES = [
+    "branding/brand.yaml",
+    "branding/brand.yml",
+    "branding/brand.json",
+    "brand.yaml",
+    "brand.yml",
+    "brand.json",
+];
+export const BrandContextSchema = sharedBrand.BrandContextSchema;
+export const defaultBrandContext = sharedBrand.defaultBrandContext;
+export const parseBrandContext = sharedBrand.parseBrandContext;
+export const brandContextJsonSchema = sharedBrand.brandContextJsonSchema;
+export const brandContextPrompt = sharedBrand.brandContextPrompt;
+/** Find a conventional YAML or JSON brand file from known project roots. */
+export function findBrandContextFile(cwd = process.cwd()) {
+    for (const root of resolveProjectRoots(cwd)) {
+        for (const candidate of BRAND_CONTEXT_FILES) {
+            const path = resolve(root, candidate);
+            if (statSync(path)?.isFile())
+                return path;
+        }
+    }
+    return undefined;
+}
+/** Read and validate one `.yaml`, `.yml`, or `.json` brand context file. */
+export async function loadBrandContextFile(path) {
+    const source = await readFile(path, "utf8");
+    const extension = extname(path).toLowerCase();
+    let input;
+    if (extension === ".json") {
+        input = JSON.parse(source);
+    }
+    else if (extension === ".yaml" || extension === ".yml") {
+        const { parse } = await import("yaml");
+        input = parse(source);
+    }
+    else {
+        throw new Error(`Unsupported brand context format: ${extension || "no extension"}`);
+    }
+    return sharedBrand.parseBrandContext(input);
+}
+/**
+ * Discover and load a brand context. Missing files resolve to dbx tools defaults;
+ * malformed files fail with their parser or Zod validation error.
+ */
+export async function loadBrandContext(cwd = process.cwd()) {
+    const path = findBrandContextFile(cwd);
+    return path ? loadBrandContextFile(path) : sharedBrand.defaultBrandContext;
+}
+/** Resolve a relative asset reference against the brand file that declared it. */
+export function resolveBrandAssetPath(brandFile, asset) {
+    if (isAbsolute(asset) ||
+        asset.startsWith("@") ||
+        asset.startsWith("//") ||
+        /^[a-z][a-z\d+.-]*:/i.test(asset)) {
+        return asset;
+    }
+    return resolve(dirname(brandFile), asset);
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiYnJhbmQuanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi9zcmMvYnJhbmQudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQUEseUVBQXlFO0FBQ3pFLE9BQU8sRUFBRSxRQUFRLEVBQUUsTUFBTSxrQkFBa0IsQ0FBQztBQUM1QyxPQUFPLEVBQUUsT0FBTyxFQUFFLE9BQU8sRUFBRSxVQUFVLEVBQUUsT0FBTyxFQUFFLE1BQU0sV0FBVyxDQUFDO0FBQ2xFLE9BQU8sRUFBRSxLQUFLLElBQUksV0FBVyxFQUFFLE1BQU0sd0JBQXdCLENBQUM7QUFDOUQsT0FBTyxFQUFFLFFBQVEsRUFBRSxNQUFNLFFBQVEsQ0FBQztBQUNsQyxPQUFPLEVBQUUsbUJBQW1CLEVBQUUsTUFBTSxXQUFXLENBQUM7QUFFaEQsTUFBTSxtQkFBbUIsR0FBRztJQUMxQixxQkFBcUI7SUFDckIsb0JBQW9CO0lBQ3BCLHFCQUFxQjtJQUNyQixZQUFZO0lBQ1osV0FBVztJQUNYLFlBQVk7Q0FDSixDQUFDO0FBSVgsTUFBTSxDQUFDLE1BQU0sa0JBQWtCLEdBQUcsV0FBVyxDQUFDLGtCQUFrQixDQUFDO0FBQ2pFLE1BQU0sQ0FBQyxNQUFNLG1CQUFtQixHQUFHLFdBQVcsQ0FBQyxtQkFBbUIsQ0FBQztBQUNuRSxNQUFNLENBQUMsTUFBTSxpQkFBaUIsR0FBRyxXQUFXLENBQUMsaUJBQWlCLENBQUM7QUFDL0QsTUFBTSxDQUFDLE1BQU0sc0JBQXNCLEdBQUcsV0FBVyxDQUFDLHNCQUFzQixDQUFDO0FBQ3pFLE1BQU0sQ0FBQyxNQUFNLGtCQUFrQixHQUFHLFdBQVcsQ0FBQyxrQkFBa0IsQ0FBQztBQUVqRSw0RUFBNEU7QUFDNUUsTUFBTSxVQUFVLG9CQUFvQixDQUFDLE1BQWMsT0FBTyxDQUFDLEdBQUcsRUFBRTtJQUM5RCxLQUFLLE1BQU0sSUFBSSxJQUFJLG1CQUFtQixDQUFDLEdBQUcsQ0FBQyxFQUFFLENBQUM7UUFDNUMsS0FBSyxNQUFNLFNBQVMsSUFBSSxtQkFBbUIsRUFBRSxDQUFDO1lBQzVDLE1BQU0sSUFBSSxHQUFHLE9BQU8sQ0FBQyxJQUFJLEVBQUUsU0FBUyxDQUFDLENBQUM7WUFDdEMsSUFBSSxRQUFRLENBQUMsSUFBSSxDQUFDLEVBQUUsTUFBTSxFQUFFO2dCQUFFLE9BQU8sSUFBSSxDQUFDO1FBQzVDLENBQUM7SUFDSCxDQUFDO0lBQ0QsT0FBTyxTQUFTLENBQUM7QUFDbkIsQ0FBQztBQUVELDRFQUE0RTtBQUM1RSxNQUFNLENBQUMsS0FBSyxVQUFVLG9CQUFvQixDQUFDLElBQVk7SUFDckQsTUFBTSxNQUFNLEdBQUcsTUFBTSxRQUFRLENBQUMsSUFBSSxFQUFFLE1BQU0sQ0FBQyxDQUFDO0lBQzVDLE1BQU0sU0FBUyxHQUFHLE9BQU8sQ0FBQyxJQUFJLENBQUMsQ0FBQyxXQUFXLEVBQUUsQ0FBQztJQUM5QyxJQUFJLEtBQWMsQ0FBQztJQUVuQixJQUFJLFNBQVMsS0FBSyxPQUFPLEVBQUUsQ0FBQztRQUMxQixLQUFLLEdBQUcsSUFBSSxDQUFDLEtBQUssQ0FBQyxNQUFNLENBQVksQ0FBQztJQUN4QyxDQUFDO1NBQU0sSUFBSSxTQUFTLEtBQUssT0FBTyxJQUFJLFNBQVMsS0FBSyxNQUFNLEVBQUUsQ0FBQztRQUN6RCxNQUFNLEVBQUUsS0FBSyxFQUFFLEdBQUcsTUFBTSxNQUFNLENBQUMsTUFBTSxDQUFDLENBQUM7UUFDdkMsS0FBSyxHQUFHLEtBQUssQ0FBQyxNQUFNLENBQVksQ0FBQztJQUNuQyxDQUFDO1NBQU0sQ0FBQztRQUNOLE1BQU0sSUFBSSxLQUFLLENBQUMscUNBQXFDLFNBQVMsSUFBSSxjQUFjLEVBQUUsQ0FBQyxDQUFDO0lBQ3RGLENBQUM7SUFFRCxPQUFPLFdBQVcsQ0FBQyxpQkFBaUIsQ0FBQyxLQUFLLENBQUMsQ0FBQztBQUM5QyxDQUFDO0FBRUQ7OztHQUdHO0FBQ0gsTUFBTSxDQUFDLEtBQUssVUFBVSxnQkFBZ0IsQ0FBQyxNQUFjLE9BQU8sQ0FBQyxHQUFHLEVBQUU7SUFDaEUsTUFBTSxJQUFJLEdBQUcsb0JBQW9CLENBQUMsR0FBRyxDQUFDLENBQUM7SUFDdkMsT0FBTyxJQUFJLENBQUMsQ0FBQyxDQUFDLG9CQUFvQixDQUFDLElBQUksQ0FBQyxDQUFDLENBQUMsQ0FBQyxXQUFXLENBQUMsbUJBQW1CLENBQUM7QUFDN0UsQ0FBQztBQUVELGtGQUFrRjtBQUNsRixNQUFNLFVBQVUscUJBQXFCLENBQUMsU0FBaUIsRUFBRSxLQUFhO0lBQ3BFLElBQ0UsVUFBVSxDQUFDLEtBQUssQ0FBQztRQUNqQixLQUFLLENBQUMsVUFBVSxDQUFDLEdBQUcsQ0FBQztRQUNyQixLQUFLLENBQUMsVUFBVSxDQUFDLElBQUksQ0FBQztRQUN0QixxQkFBcUIsQ0FBQyxJQUFJLENBQUMsS0FBSyxDQUFDLEVBQ2pDLENBQUM7UUFDRCxPQUFPLEtBQUssQ0FBQztJQUNmLENBQUM7SUFDRCxPQUFPLE9BQU8sQ0FBQyxPQUFPLENBQUMsU0FBUyxDQUFDLEVBQUUsS0FBSyxDQUFDLENBQUM7QUFDNUMsQ0FBQyIsInNvdXJjZXNDb250ZW50IjpbIi8qKiBOb2RlLW9ubHkgZGlzY292ZXJ5IGFuZCBmaWxlIGxvYWRpbmcgZm9yIHRoZSBzaGFyZWQgYnJhbmQgY29udGV4dC4gKi9cbmltcG9ydCB7IHJlYWRGaWxlIH0gZnJvbSBcIm5vZGU6ZnMvcHJvbWlzZXNcIjtcbmltcG9ydCB7IGRpcm5hbWUsIGV4dG5hbWUsIGlzQWJzb2x1dGUsIHJlc29sdmUgfSBmcm9tIFwibm9kZTpwYXRoXCI7XG5pbXBvcnQgeyBicmFuZCBhcyBzaGFyZWRCcmFuZCB9IGZyb20gXCJAZGJ4LXRvb2xzL3NoYXJlZC1jb3JlXCI7XG5pbXBvcnQgeyBzdGF0U3luYyB9IGZyb20gXCIuL2ZpbGVcIjtcbmltcG9ydCB7IHJlc29sdmVQcm9qZWN0Um9vdHMgfSBmcm9tIFwiLi9wcm9qZWN0XCI7XG5cbmNvbnN0IEJSQU5EX0NPTlRFWFRfRklMRVMgPSBbXG4gIFwiYnJhbmRpbmcvYnJhbmQueWFtbFwiLFxuICBcImJyYW5kaW5nL2JyYW5kLnltbFwiLFxuICBcImJyYW5kaW5nL2JyYW5kLmpzb25cIixcbiAgXCJicmFuZC55YW1sXCIsXG4gIFwiYnJhbmQueW1sXCIsXG4gIFwiYnJhbmQuanNvblwiLFxuXSBhcyBjb25zdDtcblxuZXhwb3J0IHR5cGUgQnJhbmRDb250ZXh0ID0gc2hhcmVkQnJhbmQuQnJhbmRDb250ZXh0O1xuZXhwb3J0IHR5cGUgQnJhbmRDb250ZXh0SW5wdXQgPSBzaGFyZWRCcmFuZC5CcmFuZENvbnRleHRJbnB1dDtcbmV4cG9ydCBjb25zdCBCcmFuZENvbnRleHRTY2hlbWEgPSBzaGFyZWRCcmFuZC5CcmFuZENvbnRleHRTY2hlbWE7XG5leHBvcnQgY29uc3QgZGVmYXVsdEJyYW5kQ29udGV4dCA9IHNoYXJlZEJyYW5kLmRlZmF1bHRCcmFuZENvbnRleHQ7XG5leHBvcnQgY29uc3QgcGFyc2VCcmFuZENvbnRleHQgPSBzaGFyZWRCcmFuZC5wYXJzZUJyYW5kQ29udGV4dDtcbmV4cG9ydCBjb25zdCBicmFuZENvbnRleHRKc29uU2NoZW1hID0gc2hhcmVkQnJhbmQuYnJhbmRDb250ZXh0SnNvblNjaGVtYTtcbmV4cG9ydCBjb25zdCBicmFuZENvbnRleHRQcm9tcHQgPSBzaGFyZWRCcmFuZC5icmFuZENvbnRleHRQcm9tcHQ7XG5cbi8qKiBGaW5kIGEgY29udmVudGlvbmFsIFlBTUwgb3IgSlNPTiBicmFuZCBmaWxlIGZyb20ga25vd24gcHJvamVjdCByb290cy4gKi9cbmV4cG9ydCBmdW5jdGlvbiBmaW5kQnJhbmRDb250ZXh0RmlsZShjd2Q6IHN0cmluZyA9IHByb2Nlc3MuY3dkKCkpOiBzdHJpbmcgfCB1bmRlZmluZWQge1xuICBmb3IgKGNvbnN0IHJvb3Qgb2YgcmVzb2x2ZVByb2plY3RSb290cyhjd2QpKSB7XG4gICAgZm9yIChjb25zdCBjYW5kaWRhdGUgb2YgQlJBTkRfQ09OVEVYVF9GSUxFUykge1xuICAgICAgY29uc3QgcGF0aCA9IHJlc29sdmUocm9vdCwgY2FuZGlkYXRlKTtcbiAgICAgIGlmIChzdGF0U3luYyhwYXRoKT8uaXNGaWxlKCkpIHJldHVybiBwYXRoO1xuICAgIH1cbiAgfVxuICByZXR1cm4gdW5kZWZpbmVkO1xufVxuXG4vKiogUmVhZCBhbmQgdmFsaWRhdGUgb25lIGAueWFtbGAsIGAueW1sYCwgb3IgYC5qc29uYCBicmFuZCBjb250ZXh0IGZpbGUuICovXG5leHBvcnQgYXN5bmMgZnVuY3Rpb24gbG9hZEJyYW5kQ29udGV4dEZpbGUocGF0aDogc3RyaW5nKTogUHJvbWlzZTxCcmFuZENvbnRleHQ+IHtcbiAgY29uc3Qgc291cmNlID0gYXdhaXQgcmVhZEZpbGUocGF0aCwgXCJ1dGY4XCIpO1xuICBjb25zdCBleHRlbnNpb24gPSBleHRuYW1lKHBhdGgpLnRvTG93ZXJDYXNlKCk7XG4gIGxldCBpbnB1dDogdW5rbm93bjtcblxuICBpZiAoZXh0ZW5zaW9uID09PSBcIi5qc29uXCIpIHtcbiAgICBpbnB1dCA9IEpTT04ucGFyc2Uoc291cmNlKSBhcyB1bmtub3duO1xuICB9IGVsc2UgaWYgKGV4dGVuc2lvbiA9PT0gXCIueWFtbFwiIHx8IGV4dGVuc2lvbiA9PT0gXCIueW1sXCIpIHtcbiAgICBjb25zdCB7IHBhcnNlIH0gPSBhd2FpdCBpbXBvcnQoXCJ5YW1sXCIpO1xuICAgIGlucHV0ID0gcGFyc2Uoc291cmNlKSBhcyB1bmtub3duO1xuICB9IGVsc2Uge1xuICAgIHRocm93IG5ldyBFcnJvcihgVW5zdXBwb3J0ZWQgYnJhbmQgY29udGV4dCBmb3JtYXQ6ICR7ZXh0ZW5zaW9uIHx8IFwibm8gZXh0ZW5zaW9uXCJ9YCk7XG4gIH1cblxuICByZXR1cm4gc2hhcmVkQnJhbmQucGFyc2VCcmFuZENvbnRleHQoaW5wdXQpO1xufVxuXG4vKipcbiAqIERpc2NvdmVyIGFuZCBsb2FkIGEgYnJhbmQgY29udGV4dC4gTWlzc2luZyBmaWxlcyByZXNvbHZlIHRvIGRieCB0b29scyBkZWZhdWx0cztcbiAqIG1hbGZvcm1lZCBmaWxlcyBmYWlsIHdpdGggdGhlaXIgcGFyc2VyIG9yIFpvZCB2YWxpZGF0aW9uIGVycm9yLlxuICovXG5leHBvcnQgYXN5bmMgZnVuY3Rpb24gbG9hZEJyYW5kQ29udGV4dChjd2Q6IHN0cmluZyA9IHByb2Nlc3MuY3dkKCkpOiBQcm9taXNlPEJyYW5kQ29udGV4dD4ge1xuICBjb25zdCBwYXRoID0gZmluZEJyYW5kQ29udGV4dEZpbGUoY3dkKTtcbiAgcmV0dXJuIHBhdGggPyBsb2FkQnJhbmRDb250ZXh0RmlsZShwYXRoKSA6IHNoYXJlZEJyYW5kLmRlZmF1bHRCcmFuZENvbnRleHQ7XG59XG5cbi8qKiBSZXNvbHZlIGEgcmVsYXRpdmUgYXNzZXQgcmVmZXJlbmNlIGFnYWluc3QgdGhlIGJyYW5kIGZpbGUgdGhhdCBkZWNsYXJlZCBpdC4gKi9cbmV4cG9ydCBmdW5jdGlvbiByZXNvbHZlQnJhbmRBc3NldFBhdGgoYnJhbmRGaWxlOiBzdHJpbmcsIGFzc2V0OiBzdHJpbmcpOiBzdHJpbmcge1xuICBpZiAoXG4gICAgaXNBYnNvbHV0ZShhc3NldCkgfHxcbiAgICBhc3NldC5zdGFydHNXaXRoKFwiQFwiKSB8fFxuICAgIGFzc2V0LnN0YXJ0c1dpdGgoXCIvL1wiKSB8fFxuICAgIC9eW2Etel1bYS16XFxkKy4tXSo6L2kudGVzdChhc3NldClcbiAgKSB7XG4gICAgcmV0dXJuIGFzc2V0O1xuICB9XG4gIHJldHVybiByZXNvbHZlKGRpcm5hbWUoYnJhbmRGaWxlKSwgYXNzZXQpO1xufVxuIl19

package/lib/src/exec.d.ts

@@ -0,0 +1,149 @@
+/**
+ * Portable subprocess helper built on `child_process.spawn` and line streaming.
+ *
+ * Ported from `dbx-tools-js/packages/cli/src/exec.ts`. Each stdio fd defaults to
+ * `"inherit"`. {@link spawn} streams output line-by-line into {@link ExecResult.stdoutLines}
+ * / {@link ExecResult.stderrLines}; its `stdout` / `stderr` getters join those lines.
+ * {@link spawnSync} keeps the captured string; its `stdout` / `stderr` getters read
+ * that string directly (line arrays split lazily on read).
+ * Omitted `trim` (default) applies adaptive normalization: {@link spawnSync} drops
+ * at most one trailing empty line / newline `spawnSync` adds; {@link spawn} does
+ * not (readline never emits that extra line). `trim: true` strips all leading/
+ * trailing whitespace in both modes; `trim: false` leaves output unchanged.
+ *
+ * @example Capture command output
+ * ```ts
+ * const { stdout } = await exec("git", ["rev-parse", "--show-toplevel"], {
+ *   stdout: "capture",
+ *   stderr: "ignore",
+ *   stdin: "ignore",
+ * });
+ * ```
+ *
+ * @example Stream and capture together
+ * ```ts
+ * await exec("pnpm", ["install"], {
+ *   stdout: [(line) => console.log(line), "capture"],
+ *   check: true,
+ * });
+ * ```
+ *
+ * @example Synchronous capture (no line callbacks)
+ * ```ts
+ * const { stdout } = execSync("git", ["rev-parse", "--show-toplevel"], {
+ *   stdout: "capture",
+ *   stderr: "ignore",
+ *   stdin: "ignore",
+ * });
+ * ```
+ *
+ * @module
+ */
+import { type SpawnOptions } from "node:child_process";
+/** Stdio mode for a subprocess fd. */
+export type ExecStdio = "inherit" | "pipe" | "ignore";
+/** Invoked once per output line when a fd is piped. */
+export type LineHandler = (line: string) => void;
+/**
+ * Stdio config for one fd.
+ *
+ * - `"inherit"` / `"pipe"` / `"ignore"` — pass through to `spawn`
+ * - `"capture"` — pipe the fd and append each line to the result
+ * - {@link LineHandler} — pipe and invoke the handler per line (lines are still captured)
+ * - `(LineHandler | "capture")[]` — pipe; `"capture"` is a no-op marker, handlers run per line
+ */
+export type StdioOption = ExecStdio | LineHandler | "capture" | (LineHandler | "capture")[];
+/** Outcome of {@link spawn} / {@link spawnSync}: exit code, captured output, and line views. */
+export type ExecResult = {
+    exitCode: number;
+    /**
+     * Captured stdout lines. For {@link spawn} these are built while the process runs;
+     * for {@link spawnSync} they are split from the captured string on first read.
+     */
+    readonly stdoutLines: string[];
+    /**
+     * Captured stderr lines. For {@link spawn} these are built while the process runs;
+     * for {@link spawnSync} they are split from the captured string on first read.
+     */
+    readonly stderrLines: string[];
+    /**
+     * Captured stdout text. {@link spawnSync} reads the captured string;
+     * {@link spawn} joins {@link stdoutLines}. See `trim` for normalization.
+     */
+    readonly stdout: string;
+    /**
+     * Captured stderr text. {@link spawnSync} reads the captured string;
+     * {@link spawn} joins {@link stderrLines}. See `trim` for normalization.
+     */
+    readonly stderr: string;
+};
+/** Options for {@link spawn}. Extends `SpawnOptions` except `stdio`, which is driven by `stdin` / `stdout` / `stderr`. */
+export type ExecOptions = Omit<SpawnOptions, "stdio"> & {
+    /** `"inherit"` by default, or a string written to the process stdin. */
+    stdin?: ExecStdio | string;
+    stdout?: StdioOption;
+    stderr?: StdioOption;
+    /** Throw when the process exits with a non-zero code. */
+    check?: boolean;
+    /**
+     * Omitted — adaptive trim ({@link spawnSync} drops one spawn trailing newline,
+     * {@link spawn} does not); `true` — strip all leading/trailing whitespace;
+     * `false` — leave captured output unchanged.
+     */
+    trim?: boolean;
+};
+/** Stdio mode for {@link spawnSync} (no per-line callbacks). */
+export type SyncExecStdio = ExecStdio | "capture";
+/** Options for {@link spawnSync}. Same shape as {@link ExecOptions} but without line-handler stdio. */
+export type SyncExecOptions = Omit<SpawnOptions, "stdio"> & {
+    /** `"inherit"` by default, or a string written to the process stdin. */
+    stdin?: ExecStdio | string;
+    stdout?: SyncExecStdio;
+    stderr?: SyncExecStdio;
+    /** Throw when the process exits with a non-zero code. */
+    check?: boolean;
+    /**
+     * Omitted — adaptive trim ({@link spawnSync} drops one spawn trailing newline,
+     * {@link spawn} does not); `true` — strip all leading/trailing whitespace;
+     * `false` — leave captured output unchanged.
+     */
+    trim?: boolean;
+};
+export type SpawnArgs<T extends SpawnOptions> = [command: string, ...args: string[]] | [command: string, args: readonly string[]] | [command: string, args: readonly string[], options: T] | [command: string, ...argsAndOptions: [...string[], T]];
+/**
+ * Spawn a subprocess and wait for exit.
+ *
+ * @param command - Executable to run (resolved on `PATH` when `shell` is set on options)
+ * @param args - Arguments passed verbatim to the executable
+ * @param options - Spawn, stdio, and check options
+ * @returns Exit code, captured line arrays, and trimmed `stdout` / `stderr` getters
+ * @throws When spawn fails, line reads fail, or `check` is true and exit code is non-zero
+ */
+export declare function spawn(...args: SpawnArgs<ExecOptions>): Promise<ExecResult>;
+/**
+ * Spawn a subprocess synchronously and wait for exit.
+ *
+ * Unlike {@link spawn}, stdio options are limited to `"inherit"`, `"pipe"`,
+ * `"ignore"`, and `"capture"` — no per-line callbacks.
+ *
+ * @param command - Executable to run (resolved on `PATH` when `shell` is set on options)
+ * @param args - Arguments passed verbatim to the executable
+ * @param spawnSync - Spawn, stdio, and check options
+ * @returns Exit code, captured line arrays, and trimmed `stdout` / `stderr` getters
+ * @throws When spawn fails or `check` is true and exit code is non-zero
+ */
+export declare function spawnSync(...args: SpawnArgs<SyncExecOptions>): ExecResult;
+/**
+ * Splits a shell-like command into argv.
+ *
+ * Supports:
+ *   - whitespace separators
+ *   - single and double quotes
+ *   - backslash escaping
+ *   - escaped spaces
+ *   - empty quoted strings
+ *
+ * If the input is malformed (for example, an unterminated quote),
+ * returns the original string as a single argument.
+ */
+export declare function shlex(command: string): string[];