@birdycom/omniaui 0.11.0 → 0.11.1

package/bin/lib/catalog.mjs

@@ -1,169 +1,169 @@
-// File: packages/ui/bin/lib/catalog.mjs
-// What can be added, per flavour (css | vue | react | blade), and which files an entry needs.
-// Map: registry (snippet manifests) -> flavourRoot -> catalog -> closure (internal imports) -> findEntries
-
-import fs from "node:fs/promises";
-import path from "node:path";
-import { binDir, cwd, exists, kebab, pkgDir, posix, readJson } from "./project.mjs";
-
-export const INSTALL_HINT = { vue: "npm i @birdycom/omniaui-vue", react: "npm i @birdycom/omniaui-react", blade: "composer require birdycom/omniaui-laravel", block: "npm i @birdycom/omniaui-blocks" };
-
-// Package roots inside the OmniaUI monorepo (used when the package is not installed, e.g. while developing).
-const uiRoot = path.resolve(binDir, "..");
-const monoPackages = path.resolve(binDir, "../..");
-const monoBlade = path.resolve(binDir, "../../../php-packages/omniaui-laravel/resources/views/components");
-
-/** Folder of a package, or a monorepo fallback folder, or null. */
-async function findPkg(name, fallback) {
-  try { return pkgDir(name); } catch { /* not installed */ }
-  return (await exists(path.join(fallback, "package.json"))) ? fallback : null;
-}
-
-const registryCache = {};
-/** Snippet registry: { dir, manifest } of @birdycom/omniaui (components) or @birdycom/omniaui-blocks (blocks). */
-export async function registry(kind) {
-  if (!registryCache[kind]) {
-    const dir = kind === "block" ? await findPkg("@birdycom/omniaui-blocks", path.join(monoPackages, "blocks")) : uiRoot;
-    if (!dir) throw new Error(`Cannot find the blocks. Install them with: ${INSTALL_HINT.block}`);
-    registryCache[kind] = { dir, manifest: await readJson(path.join(dir, "manifest.json")) };
-  }
-  return registryCache[kind];
-}
-
-/** OmniaUI Pro snippets ({ dir, manifest }) when @birdycom/omniaui-pro is installed, else null. */
-async function proRegistry() {
-  try {
-    const dir = pkgDir("@birdycom/omniaui-pro");
-    return { dir, manifest: await readJson(path.join(dir, "manifest.json")) };
-  } catch { return null; }
-}
-
-/** Names of the OmniaUI Pro blocks (pro.json in @birdycom/omniaui-blocks), for a hint when one is asked for without Pro. */
-export async function proBlockNames() {
-  try { return (await readJson(path.join((await registry("block")).dir, "pro.json"))).items.map((i) => i.name); } catch { return []; }
-}
-
-/** Root folder holding the sources of a flavour (installed package first, monorepo second). Returns null when missing. */
-async function flavourRoot(fw) {
-  if (fw === "vue" || fw === "react") return findPkg(`@birdycom/omniaui-${fw}`, path.join(monoPackages, fw));
-  if (fw === "blade") {
-    for (const base of [path.join(cwd, "vendor/birdycom/omniaui-laravel/resources/views/components"), monoBlade]) {
-      if (await exists(base)) return base;
-    }
-  }
-  return null;
-}
-
-async function walk(dir, base = dir) {
-  const out = [];
-  for (const e of await fs.readdir(dir, { withFileTypes: true })) {
-    const full = path.join(dir, e.name);
-    if (e.isDirectory()) out.push(...(await walk(full, base)));
-    else out.push(posix(path.relative(base, full)));
-  }
-  return out.sort();
-}
-
-/** Snippet name of a vue manifest item (sub-parts share the snippet of their parent). */
-const vueSnippetName = (i) => (i.snippet ? path.basename(i.snippet, ".html") : kebab(i.name.replace(/^Oc(Block)?/, "")));
-
-/**
- * Catalog of one flavour: { root, entries: [{ kind, name, files (relative to root), description }] }.
- * An entry groups the files that belong together (Accordion + AccordionItem, accordion.blade.php + accordion/).
- */
-export async function catalog(fw) {
-  const describe = {};
-  const regs = {};
-  for (const kind of ["component", "block"]) {
-    // Blocks are optional (separate package): without them, only components are listed.
-    try { regs[kind] = await registry(kind); } catch (err) { if (kind === "component") throw err; regs[kind] = null; }
-    for (const i of regs[kind]?.manifest.items || []) describe[`${kind}:${i.name}`] = i;
-  }
-  if (fw === "css") {
-    const entries = [];
-    for (const kind of ["component", "block"]) {
-      for (const i of regs[kind]?.manifest.items || []) entries.push({ kind, name: i.name, files: [i.file], description: i.description, root: regs[kind].dir });
-    }
-    const pro = await proRegistry();
-    for (const i of pro?.manifest.items || []) entries.push({ kind: "block", name: i.name, files: [i.file], description: i.description, root: pro.dir, pro: true });
-    return { root: null, entries };
-  }
-  const root = await flavourRoot(fw);
-  if (!root) throw new Error(`Cannot find the ${fw} sources. Install them with: ${INSTALL_HINT[fw]}`);
-  const groups = new Map();
-  const put = (kind, name, file) => {
-    const key = `${kind}:${name}`;
-    if (!groups.has(key)) groups.set(key, { kind, name, files: [], description: describe[key]?.description });
-    groups.get(key).files.push(file);
-  };
-  if (fw === "blade") {
-    for (const file of await walk(root)) {
-      if (!file.endsWith(".blade.php")) continue;
-      const segs = file.slice(0, -".blade.php".length).split("/");
-      if (segs[0] === "block" && segs.length > 1) put("block", segs[1], file);
-      else put("component", segs[0], file);
-    }
-  } else {
-    const manifest = await readJson(path.join(root, "manifest.json"));
-    // react: one entry per name; vue: parts that share an HTML snippet belong to one entry
-    for (const i of manifest.items) put(i.kind, fw === "vue" ? vueSnippetName(i) : i.name, i.file);
-  }
-  return { root, entries: [...groups.values()].sort((a, b) => a.name.localeCompare(b.name)) };
-}
-
-const EXT = ["", ".ts", ".tsx", ".vue", "/index.ts", "/index.tsx"];
-/** Local files a vue/react source imports (relative specifiers only). */
-async function localImports(root, file) {
-  const text = await fs.readFile(path.join(root, file), "utf8");
-  const found = [];
-  for (const m of text.matchAll(/(?:from|import)\s*["'](\.{1,2}\/[^"']+)["']/g)) {
-    const base = path.posix.normalize(path.posix.join(path.posix.dirname(file), m[1]));
-    for (const ext of EXT) {
-      if (path.extname(base + ext) && (await fs.stat(path.join(root, base + ext)).catch(() => null))?.isFile()) { found.push(base + ext); break; }
-    }
-  }
-  return found;
-}
-
-/** Blade components a file uses, as files: <x-oc::button> -> button.blade.php, <x-oc::block.hero> -> block/hero.blade.php. */
-async function bladeUses(root, file) {
-  const text = await fs.readFile(path.join(root, file), "utf8");
-  const found = new Set();
-  for (const m of text.matchAll(/<x-oc::([\w.-]+)/g)) {
-    const rel = `${m[1].replace(/\./g, "/")}.blade.php`;
-    if (await exists(path.join(root, rel))) found.add(rel);
-  }
-  return [...found];
-}
-
-/** All files an entry needs: its own files plus internal dependencies (utils, hooks, composables, sub-components). */
-export async function closure(fw, root, entry, entries) {
-  const seen = new Set();
-  const queue = [...entry.files];
-  while (queue.length) {
-    const file = queue.shift();
-    if (seen.has(file)) continue;
-    seen.add(file);
-    const deps = fw === "blade" ? await bladeUses(root, file) : await localImports(root, file);
-    for (const dep of deps) {
-      queue.push(dep);
-      // blade: pull in the whole entry (root file + sub-parts like accordion/item)
-      if (fw === "blade") {
-        const owner = entries.find((e) => e.files.includes(dep));
-        if (owner) queue.push(...owner.files);
-      }
-    }
-  }
-  return [...seen].sort();
-}
-
-/** Find the entries for a user-typed name ("button", "OcButton", "app-shell"). */
-export function findEntries(entries, input, kind) {
-  let name = kebab(input);
-  if (name.startsWith("oc-")) name = name.slice(3);
-  if (name.startsWith("block-") && !kind) {
-    const hit = entries.filter((e) => e.kind === "block" && e.name === name.slice(6));
-    if (hit.length) return hit;
-  }
-  return entries.filter((e) => e.name === name && (!kind || e.kind === kind));
-}
+// File: packages/ui/bin/lib/catalog.mjs
+// What can be added, per flavour (css | vue | react | blade), and which files an entry needs.
+// Map: registry (snippet manifests) -> flavourRoot -> catalog -> closure (internal imports) -> findEntries
+
+import fs from "node:fs/promises";
+import path from "node:path";
+import { binDir, cwd, exists, kebab, pkgDir, posix, readJson } from "./project.mjs";
+
+export const INSTALL_HINT = { vue: "npm i @birdycom/omniaui-vue", react: "npm i @birdycom/omniaui-react", blade: "composer require birdycom/omniaui-laravel", block: "npm i @birdycom/omniaui-blocks" };
+
+// Package roots inside the OmniaUI monorepo (used when the package is not installed, e.g. while developing).
+const uiRoot = path.resolve(binDir, "..");
+const monoPackages = path.resolve(binDir, "../..");
+const monoBlade = path.resolve(binDir, "../../../php-packages/omniaui-laravel/resources/views/components");
+
+/** Folder of a package, or a monorepo fallback folder, or null. */
+async function findPkg(name, fallback) {
+  try { return pkgDir(name); } catch { /* not installed */ }
+  return (await exists(path.join(fallback, "package.json"))) ? fallback : null;
+}
+
+const registryCache = {};
+/** Snippet registry: { dir, manifest } of @birdycom/omniaui (components) or @birdycom/omniaui-blocks (blocks). */
+export async function registry(kind) {
+  if (!registryCache[kind]) {
+    const dir = kind === "block" ? await findPkg("@birdycom/omniaui-blocks", path.join(monoPackages, "blocks")) : uiRoot;
+    if (!dir) throw new Error(`Cannot find the blocks. Install them with: ${INSTALL_HINT.block}`);
+    registryCache[kind] = { dir, manifest: await readJson(path.join(dir, "manifest.json")) };
+  }
+  return registryCache[kind];
+}
+
+/** OmniaUI Pro snippets ({ dir, manifest }) when @birdycom/omniaui-pro is installed, else null. */
+async function proRegistry() {
+  try {
+    const dir = pkgDir("@birdycom/omniaui-pro");
+    return { dir, manifest: await readJson(path.join(dir, "manifest.json")) };
+  } catch { return null; }
+}
+
+/** Names of the OmniaUI Pro blocks (pro.json in @birdycom/omniaui-blocks), for a hint when one is asked for without Pro. */
+export async function proBlockNames() {
+  try { return (await readJson(path.join((await registry("block")).dir, "pro.json"))).items.map((i) => i.name); } catch { return []; }
+}
+
+/** Root folder holding the sources of a flavour (installed package first, monorepo second). Returns null when missing. */
+async function flavourRoot(fw) {
+  if (fw === "vue" || fw === "react") return findPkg(`@birdycom/omniaui-${fw}`, path.join(monoPackages, fw));
+  if (fw === "blade") {
+    for (const base of [path.join(cwd, "vendor/birdycom/omniaui-laravel/resources/views/components"), monoBlade]) {
+      if (await exists(base)) return base;
+    }
+  }
+  return null;
+}
+
+async function walk(dir, base = dir) {
+  const out = [];
+  for (const e of await fs.readdir(dir, { withFileTypes: true })) {
+    const full = path.join(dir, e.name);
+    if (e.isDirectory()) out.push(...(await walk(full, base)));
+    else out.push(posix(path.relative(base, full)));
+  }
+  return out.sort();
+}
+
+/** Snippet name of a vue manifest item (sub-parts share the snippet of their parent). */
+const vueSnippetName = (i) => (i.snippet ? path.basename(i.snippet, ".html") : kebab(i.name.replace(/^Oc(Block)?/, "")));
+
+/**
+ * Catalog of one flavour: { root, entries: [{ kind, name, files (relative to root), description }] }.
+ * An entry groups the files that belong together (Accordion + AccordionItem, accordion.blade.php + accordion/).
+ */
+export async function catalog(fw) {
+  const describe = {};
+  const regs = {};
+  for (const kind of ["component", "block"]) {
+    // Blocks are optional (separate package): without them, only components are listed.
+    try { regs[kind] = await registry(kind); } catch (err) { if (kind === "component") throw err; regs[kind] = null; }
+    for (const i of regs[kind]?.manifest.items || []) describe[`${kind}:${i.name}`] = i;
+  }
+  if (fw === "css") {
+    const entries = [];
+    for (const kind of ["component", "block"]) {
+      for (const i of regs[kind]?.manifest.items || []) entries.push({ kind, name: i.name, files: [i.file], description: i.description, root: regs[kind].dir });
+    }
+    const pro = await proRegistry();
+    for (const i of pro?.manifest.items || []) entries.push({ kind: "block", name: i.name, files: [i.file], description: i.description, root: pro.dir, pro: true });
+    return { root: null, entries };
+  }
+  const root = await flavourRoot(fw);
+  if (!root) throw new Error(`Cannot find the ${fw} sources. Install them with: ${INSTALL_HINT[fw]}`);
+  const groups = new Map();
+  const put = (kind, name, file) => {
+    const key = `${kind}:${name}`;
+    if (!groups.has(key)) groups.set(key, { kind, name, files: [], description: describe[key]?.description });
+    groups.get(key).files.push(file);
+  };
+  if (fw === "blade") {
+    for (const file of await walk(root)) {
+      if (!file.endsWith(".blade.php")) continue;
+      const segs = file.slice(0, -".blade.php".length).split("/");
+      if (segs[0] === "block" && segs.length > 1) put("block", segs[1], file);
+      else put("component", segs[0], file);
+    }
+  } else {
+    const manifest = await readJson(path.join(root, "manifest.json"));
+    // react: one entry per name; vue: parts that share an HTML snippet belong to one entry
+    for (const i of manifest.items) put(i.kind, fw === "vue" ? vueSnippetName(i) : i.name, i.file);
+  }
+  return { root, entries: [...groups.values()].sort((a, b) => a.name.localeCompare(b.name)) };
+}
+
+const EXT = ["", ".ts", ".tsx", ".vue", "/index.ts", "/index.tsx"];
+/** Local files a vue/react source imports (relative specifiers only). */
+async function localImports(root, file) {
+  const text = await fs.readFile(path.join(root, file), "utf8");
+  const found = [];
+  for (const m of text.matchAll(/(?:from|import)\s*["'](\.{1,2}\/[^"']+)["']/g)) {
+    const base = path.posix.normalize(path.posix.join(path.posix.dirname(file), m[1]));
+    for (const ext of EXT) {
+      if (path.extname(base + ext) && (await fs.stat(path.join(root, base + ext)).catch(() => null))?.isFile()) { found.push(base + ext); break; }
+    }
+  }
+  return found;
+}
+
+/** Blade components a file uses, as files: <x-oc::button> -> button.blade.php, <x-oc::block.hero> -> block/hero.blade.php. */
+async function bladeUses(root, file) {
+  const text = await fs.readFile(path.join(root, file), "utf8");
+  const found = new Set();
+  for (const m of text.matchAll(/<x-oc::([\w.-]+)/g)) {
+    const rel = `${m[1].replace(/\./g, "/")}.blade.php`;
+    if (await exists(path.join(root, rel))) found.add(rel);
+  }
+  return [...found];
+}
+
+/** All files an entry needs: its own files plus internal dependencies (utils, hooks, composables, sub-components). */
+export async function closure(fw, root, entry, entries) {
+  const seen = new Set();
+  const queue = [...entry.files];
+  while (queue.length) {
+    const file = queue.shift();
+    if (seen.has(file)) continue;
+    seen.add(file);
+    const deps = fw === "blade" ? await bladeUses(root, file) : await localImports(root, file);
+    for (const dep of deps) {
+      queue.push(dep);
+      // blade: pull in the whole entry (root file + sub-parts like accordion/item)
+      if (fw === "blade") {
+        const owner = entries.find((e) => e.files.includes(dep));
+        if (owner) queue.push(...owner.files);
+      }
+    }
+  }
+  return [...seen].sort();
+}
+
+/** Find the entries for a user-typed name ("button", "OcButton", "app-shell"). */
+export function findEntries(entries, input, kind) {
+  let name = kebab(input);
+  if (name.startsWith("oc-")) name = name.slice(3);
+  if (name.startsWith("block-") && !kind) {
+    const hit = entries.filter((e) => e.kind === "block" && e.name === name.slice(6));
+    if (hit.length) return hit;
+  }
+  return entries.filter((e) => e.name === name && (!kind || e.kind === kind));
+}

package/bin/lib/project.mjs

@@ -1,90 +1,90 @@
-// File: packages/ui/bin/lib/project.mjs
-// Project helpers for the omniaui CLI: paths, package resolving, config, framework detection, content globs.
-// Map: cwd + resolve -> config (omnia.config.json) -> detectFramework / resolveFramework -> defaultDir -> ensureContentGlob
-
-import fs from "node:fs/promises";
-import path from "node:path";
-import { createRequire } from "node:module";
-import { fileURLToPath } from "node:url";
-
-export const cwd = process.cwd();
-export const CONFIG = "omnia.config.json";
-export const FRAMEWORKS = ["css", "vue", "react", "blade"];
-// Folder of the omniaui CLI (packages/ui/bin); the package root is one level up.
-export const binDir = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
-export const requireFromProject = createRequire(path.join(cwd, "package.json"));
-const requireFromCli = createRequire(path.join(binDir, "omniaui.mjs"));
-
-export const exists = async (p) => !!(await fs.stat(p).catch(() => null));
-export const posix = (p) => p.split(path.sep).join("/");
-export const kebab = (s) => s.replace(/([a-z0-9])([A-Z])/g, "$1-$2").replace(/[_\s]+/g, "-").toLowerCase();
-export const pascal = (s) => s.split("-").map((w) => w.charAt(0).toUpperCase() + w.slice(1)).join("");
-
-export async function readJson(file) {
-  return JSON.parse(await fs.readFile(file, "utf8"));
-}
-
-/** Folder of an installed package: the project's own install first, then next to the CLI. Throws when missing. */
-export function pkgDir(name) {
-  for (const req of [requireFromProject, requireFromCli]) {
-    try { return path.dirname(req.resolve(`${name}/package.json`)); } catch { /* try next */ }
-  }
-  throw new Error(`Cannot find ${name}. Install it with: npm install ${name}`);
-}
-
-/** omnia.config.json of the project ({} when there is none). */
-export async function loadConfig() {
-  try { return await readJson(path.join(cwd, CONFIG)); } catch { return {}; }
-}
-
-/** Detect the flavour from package.json / composer.json: vue, react, blade (Laravel) or css. */
-export async function detectFramework() {
-  let pkg = {};
-  try { pkg = await readJson(path.join(cwd, "package.json")); } catch { /* no package.json */ }
-  const deps = { ...pkg.dependencies, ...pkg.devDependencies };
-  if (deps.vue || deps.nuxt) return "vue";
-  if (deps.react || deps.next) return "react";
-  let laravel = await exists(path.join(cwd, "artisan"));
-  if (!laravel) {
-    try { const c = await readJson(path.join(cwd, "composer.json")); laravel = !!{ ...c.require, ...c["require-dev"] }["laravel/framework"]; } catch { /* no composer.json */ }
-  }
-  return laravel ? "blade" : "css";
-}
-
-/** Pick the flavour: --framework flag, then config `framework`, then detection. */
-export async function resolveFramework(flags) {
-  const config = await loadConfig();
-  const fw = String(flags.framework || config.framework || (await detectFramework())).toLowerCase();
-  if (!FRAMEWORKS.includes(fw)) throw new Error(`Unknown framework "${fw}". Use one of: ${FRAMEWORKS.join(", ")}.`);
-  return fw;
-}
-
-/** Default target folder per flavour (Laravel projects get Laravel paths). */
-export async function defaultDir(fw, legacyKind) {
-  const laravel = await exists(path.join(cwd, "artisan"));
-  if (fw === "blade") return "resources/views/components/oc";
-  if (fw === "css") return legacyKind ? `omnia/${legacyKind}s` : laravel ? "resources/views/oc-snippets" : "oc-snippets";
-  return laravel || (await exists(path.join(cwd, "resources/js"))) ? "resources/js/components/oc" : "src/components/oc";
-}
-
-/** Does a content glob already cover a sample path? (tiny matcher: **, *, {a,b}) */
-function globCovers(glob, sample) {
-  const re = glob
-    .replace(/[.+^$()|[\]\\]/g, "\\$&")
-    .replace(/\{([^}]+)\}/g, (_, g) => `(${g.split(",").join("|")})`)
-    .replace(/\*\*\//g, "\u0000").replace(/\*\*/g, ".*").replace(/\*/g, "[^/]*").replace(/\u0000/g, "(?:.*/)?");
-  return new RegExp(`^${re}$`).test(sample);
-}
-
-/** Add a glob to omnia.config.json so "omniacss build" scans copied files (only when a config exists). */
-export async function ensureContentGlob(glob, enableBlocks) {
-  const file = path.join(cwd, CONFIG);
-  let config;
-  try { config = await readJson(file); } catch { return; }
-  let changed = false;
-  if (enableBlocks && !config.blocks) { config.blocks = true; changed = true; console.log(`Enabled "blocks" in ${CONFIG}`); }
-  const sample = glob.replace("**/", "x/");
-  const covered = (config.content || []).some((g) => g === glob || globCovers(g, sample));
-  if (!covered) { config.content = [...(config.content || []), glob]; changed = true; console.log(`Added "${glob}" to ${CONFIG} content`); }
-  if (changed) await fs.writeFile(file, JSON.stringify(config, null, 2) + "\n");
-}
+// File: packages/ui/bin/lib/project.mjs
+// Project helpers for the omniaui CLI: paths, package resolving, config, framework detection, content globs.
+// Map: cwd + resolve -> config (omnia.config.json) -> detectFramework / resolveFramework -> defaultDir -> ensureContentGlob
+
+import fs from "node:fs/promises";
+import path from "node:path";
+import { createRequire } from "node:module";
+import { fileURLToPath } from "node:url";
+
+export const cwd = process.cwd();
+export const CONFIG = "omnia.config.json";
+export const FRAMEWORKS = ["css", "vue", "react", "blade"];
+// Folder of the omniaui CLI (packages/ui/bin); the package root is one level up.
+export const binDir = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+export const requireFromProject = createRequire(path.join(cwd, "package.json"));
+const requireFromCli = createRequire(path.join(binDir, "omniaui.mjs"));
+
+export const exists = async (p) => !!(await fs.stat(p).catch(() => null));
+export const posix = (p) => p.split(path.sep).join("/");
+export const kebab = (s) => s.replace(/([a-z0-9])([A-Z])/g, "$1-$2").replace(/[_\s]+/g, "-").toLowerCase();
+export const pascal = (s) => s.split("-").map((w) => w.charAt(0).toUpperCase() + w.slice(1)).join("");
+
+export async function readJson(file) {
+  return JSON.parse(await fs.readFile(file, "utf8"));
+}
+
+/** Folder of an installed package: the project's own install first, then next to the CLI. Throws when missing. */
+export function pkgDir(name) {
+  for (const req of [requireFromProject, requireFromCli]) {
+    try { return path.dirname(req.resolve(`${name}/package.json`)); } catch { /* try next */ }
+  }
+  throw new Error(`Cannot find ${name}. Install it with: npm install ${name}`);
+}
+
+/** omnia.config.json of the project ({} when there is none). */
+export async function loadConfig() {
+  try { return await readJson(path.join(cwd, CONFIG)); } catch { return {}; }
+}
+
+/** Detect the flavour from package.json / composer.json: vue, react, blade (Laravel) or css. */
+export async function detectFramework() {
+  let pkg = {};
+  try { pkg = await readJson(path.join(cwd, "package.json")); } catch { /* no package.json */ }
+  const deps = { ...pkg.dependencies, ...pkg.devDependencies };
+  if (deps.vue || deps.nuxt) return "vue";
+  if (deps.react || deps.next) return "react";
+  let laravel = await exists(path.join(cwd, "artisan"));
+  if (!laravel) {
+    try { const c = await readJson(path.join(cwd, "composer.json")); laravel = !!{ ...c.require, ...c["require-dev"] }["laravel/framework"]; } catch { /* no composer.json */ }
+  }
+  return laravel ? "blade" : "css";
+}
+
+/** Pick the flavour: --framework flag, then config `framework`, then detection. */
+export async function resolveFramework(flags) {
+  const config = await loadConfig();
+  const fw = String(flags.framework || config.framework || (await detectFramework())).toLowerCase();
+  if (!FRAMEWORKS.includes(fw)) throw new Error(`Unknown framework "${fw}". Use one of: ${FRAMEWORKS.join(", ")}.`);
+  return fw;
+}
+
+/** Default target folder per flavour (Laravel projects get Laravel paths). */
+export async function defaultDir(fw, legacyKind) {
+  const laravel = await exists(path.join(cwd, "artisan"));
+  if (fw === "blade") return "resources/views/components/oc";
+  if (fw === "css") return legacyKind ? `omnia/${legacyKind}s` : laravel ? "resources/views/oc-snippets" : "oc-snippets";
+  return laravel || (await exists(path.join(cwd, "resources/js"))) ? "resources/js/components/oc" : "src/components/oc";
+}
+
+/** Does a content glob already cover a sample path? (tiny matcher: **, *, {a,b}) */
+function globCovers(glob, sample) {
+  const re = glob
+    .replace(/[.+^$()|[\]\\]/g, "\\$&")
+    .replace(/\{([^}]+)\}/g, (_, g) => `(${g.split(",").join("|")})`)
+    .replace(/\*\*\//g, "\u0000").replace(/\*\*/g, ".*").replace(/\*/g, "[^/]*").replace(/\u0000/g, "(?:.*/)?");
+  return new RegExp(`^${re}$`).test(sample);
+}
+
+/** Add a glob to omnia.config.json so "omniacss build" scans copied files (only when a config exists). */
+export async function ensureContentGlob(glob, enableBlocks) {
+  const file = path.join(cwd, CONFIG);
+  let config;
+  try { config = await readJson(file); } catch { return; }
+  let changed = false;
+  if (enableBlocks && !config.blocks) { config.blocks = true; changed = true; console.log(`Enabled "blocks" in ${CONFIG}`); }
+  const sample = glob.replace("**/", "x/");
+  const covered = (config.content || []).some((g) => g === glob || globCovers(g, sample));
+  if (!covered) { config.content = [...(config.content || []), glob]; changed = true; console.log(`Added "${glob}" to ${CONFIG} content`); }
+  if (changed) await fs.writeFile(file, JSON.stringify(config, null, 2) + "\n");
+}