@dbx-tools/core 0.1.21 → 0.1.23

package/README.md

@@ -15,6 +15,21 @@ Key features:
 - Workspace/project root discovery from package-manager files, git metadata, and
   the current working directory.
 - Safe filesystem stat and project naming helpers for CLIs and projen synth.
+- YAML/JSON brand-context discovery and loading with shared Zod validation.
+
+## Load Brand Context
+
+```ts
+import { brand } from "@dbx-tools/core";
+
+const context = await brand.loadBrandContext();
+```
+
+`loadBrandContext()` searches known npm/git project roots for
+`branding/brand.yaml`, `.yml`, or `.json`, followed by equivalent root-level
+files. Missing files return the complete dbx tools default context; malformed
+files fail validation. Use `loadBrandContextFile(path)` for an explicit file and
+`resolveBrandAssetPath(path, asset)` for relative asset references.
 
 ## Run Commands
 
@@ -80,3 +95,4 @@ basename. `project.stat()` returns `undefined` instead of throwing.
 - `exec` - async/sync process spawning, stdio handling, abort wiring, and shlex.
 - `project` - root discovery, project naming, git-remote parsing, and safe
   filesystem stat.
+- `brand` - YAML/JSON discovery, parsing, validation, and asset path resolution.

package/index.ts

@@ -2,8 +2,10 @@
 // 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";
 export * as exec from "./src/exec";
 export * as file from "./src/file";
 export * as project from "./src/project";
+export type { BrandContext, BrandContextInput } from "./src/brand";
 export type { ExecStdio, LineHandler, StdioOption, ExecResult, ExecOptions, SyncExecStdio, SyncExecOptions, SpawnArgs } from "./src/exec";
 export type { ProjectContext } from "./src/project";

package/package.json

@@ -11,14 +11,15 @@
     "typescript": "^5.9.3"
   },
   "dependencies": {
-    "@dbx-tools/shared-core": "0.1.21"
+    "yaml": "^2.9.0",
+    "@dbx-tools/shared-core": "0.1.23"
   },
   "main": "index.ts",
   "license": "UNLICENSED",
   "publishConfig": {
     "access": "public"
   },
-  "version": "0.1.21",
+  "version": "0.1.23",
   "types": "index.ts",
   "type": "module",
   "exports": {

package/src/brand.ts

@@ -0,0 +1,71 @@
+/** 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";
+import { resolveProjectRoots } from "./project";
+
+const BRAND_CONTEXT_FILES = [
+  "branding/brand.yaml",
+  "branding/brand.yml",
+  "branding/brand.json",
+  "brand.yaml",
+  "brand.yml",
+  "brand.json",
+] as const;
+
+export type BrandContext = sharedBrand.BrandContext;
+export type BrandContextInput = sharedBrand.BrandContextInput;
+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: string = process.cwd()): string | undefined {
+  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: string): Promise<BrandContext> {
+  const source = await readFile(path, "utf8");
+  const extension = extname(path).toLowerCase();
+  let input: unknown;
+
+  if (extension === ".json") input = JSON.parse(source) as unknown;
+  else if (extension === ".yaml" || extension === ".yml") {
+    const { parse } = await import("yaml");
+    input = parse(source) as unknown;
+  } 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: string = process.cwd()): Promise<BrandContext> {
+  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: string, asset: string): string {
+  if (
+    isAbsolute(asset) ||
+    asset.startsWith("@") ||
+    asset.startsWith("//") ||
+    /^[a-z][a-z\d+.-]*:/i.test(asset)
+  ) {
+    return asset;
+  }
+  return resolve(dirname(brandFile), asset);
+}

package/test/brand.test.ts

@@ -0,0 +1,39 @@
+import assert from "node:assert/strict";
+import { mkdtemp, realpath, rm, writeFile, mkdir } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { describe, it } from "node:test";
+import { brand } from "../index";
+
+describe("brand files", () => {
+  it("loads YAML and discovers the conventional branding path", async () => {
+    const root = await mkdtemp(join(tmpdir(), "dbx-tools-brand-"));
+    try {
+      await writeFile(join(root, "package.json"), '{"name":"fixture"}\n');
+      await mkdir(join(root, "branding"));
+      await writeFile(join(root, "branding", "brand.yaml"), "name: Fixture\ncolors:\n  primary: '#123456'\n");
+
+      assert.equal(
+        brand.findBrandContextFile(root),
+        join(await realpath(root), "branding", "brand.yaml"),
+      );
+      const context = await brand.loadBrandContext(root);
+      assert.equal(context.name, "Fixture");
+      assert.equal(context.colors.primary, "#123456");
+    } finally {
+      await rm(root, { recursive: true, force: true });
+    }
+  });
+
+  it("loads JSON and resolves relative assets", async () => {
+    const root = await mkdtemp(join(tmpdir(), "dbx-tools-brand-"));
+    try {
+      const file = join(root, "brand.json");
+      await writeFile(file, '{"name":"JSON Fixture"}\n');
+      assert.equal((await brand.loadBrandContextFile(file)).name, "JSON Fixture");
+      assert.equal(brand.resolveBrandAssetPath(file, "assets/icon.svg"), join(root, "assets", "icon.svg"));
+    } finally {
+      await rm(root, { recursive: true, force: true });
+    }
+  });
+});