@kosdev-code/kos-asset-manager 0.0.1-next.29 → 0.0.1-next.30

package/README.md

@@ -119,6 +119,71 @@ keys when the declaration is generated:
 
 A pattern that matches nothing is reported during the build.
 
+## Media somewhere else
+
+`src/assets/media` is the ui default. A content project — a brandset, a
+descriptor pack — usually keeps its media elsewhere and ships it at a
+different path inside the kab, so both are settable:
+
+```json
+{
+  "kondra": {
+    "ui": {
+      "assets": {
+        "mediaSrc": "assets/logos",
+        "mediaRoot": "/logos",
+        "groups": { "boot": ["coke/**"] }
+      }
+    }
+  }
+}
+```
+
+`mediaSrc` is where the files are **on disk**, relative to the project root.
+`mediaRoot` is where they land **inside the kab**, which is what urls are
+built from. They are two different things — a project using vite's
+`publicDir` drops the directory name on the way out, so `assets/logos` on
+disk is `/logos` in the kab — and neither can be derived from the other.
+Leave both out and you get `src/assets/media` and `/assets/media`.
+
+Keys are still relative to `mediaSrc`, so `assets/logos/coke/pour.svg` is the
+key `coke/pour`, and bindings, groups and tags work exactly as they do
+anywhere else.
+
+The build checks its work: every declared file has to be in the build output
+under `mediaRoot`, and if none of them are the build fails naming the setting
+rather than leaving a kab whose every image 404s on the device.
+
+```
+kos-assets: 214 declared assets are not in the build output under
+/assets/media — check mediaRoot in .kos.json, and that the build copies
+the media into dist/content/ui-brandset/assets/media
+```
+
+You don't have to work either of them out by hand. `kos-assets init` looks
+for the media on disk, and reads where the build puts it out of the build
+output — exact, where guessing from the source path would be wrong for any
+project that rewrites paths on the way out:
+
+```sh
+npx nx run ui-brandset:build     # so there is an output to read
+npx kos-assets init content/ui-brandset
+```
+
+```
+kos-assets: found media in assets/logos
+kos-assets: it is served from /logos in the kab
+kos-assets: recorded the media location in content/ui-brandset/.kos.json
+kos-assets: added the assets target to content/ui-brandset/project.json
+```
+
+It writes only what it can establish and never touches a value already
+there, so a project it gets wrong is corrected by setting it and running
+again. Without a build output it records `mediaSrc` and says it could not
+tell what the root is, rather than guessing one. The target it writes then
+scans the right folder and follows the project's own `descriptor` target
+wherever that writes.
+
 ## Installing
 
 ```sh

package/bin/kos-assets.mjs

@@ -10,11 +10,13 @@
  * adds the target that runs it to the project.
  */
 import { existsSync } from 'node:fs';
-import { join, resolve } from 'node:path';
+import { dirname, join, resolve } from 'node:path';
 
 import {
-  SOURCE_DIR,
   buildAssets,
+  detectMediaRoot,
+  detectMediaSrc,
+  mediaSource,
   readJson,
   writeJson,
 } from './lib/declare-assets.mjs';
@@ -24,10 +26,129 @@ const fail = (message) => {
   process.exit(1);
 };
 
-const build = (projectRoot, out) => {
-  const descriptorPath = resolve(
-    out ?? join('dist', projectRoot, 'descriptor.json')
+/**
+ * The declared paths are only useful if the files are actually in the kab at
+ * the root the declaration names. The build output is what gets zipped, so
+ * it can be checked here -- which turns a wrong `mediaRoot` into a build
+ * error rather than an image that 404s on the device.
+ */
+const verifyContents = (assets, outputDir) => {
+  const missing = Object.values(assets.entries).filter(
+    (entry) => !existsSync(join(outputDir, assets.root, entry.path))
   );
+  if (missing.length === 0) {
+    return;
+  }
+
+  const total = Object.keys(assets.entries).length;
+  const root = assets.root || '/';
+  if (missing.length === total) {
+    fail(
+      `${total} declared assets are not in the build output under ${root} — ` +
+        `check mediaRoot in .kos.json, and that the build copies the media ` +
+        `into ${join(outputDir, assets.root)}`
+    );
+  }
+  console.warn(
+    `kos-assets: ${missing.length} of ${total} declared assets are not in ` +
+      `the build output: ${missing
+        .slice(0, 5)
+        .map((entry) => entry.path)
+        .join(', ')}${missing.length > 5 ? ', …' : ''}`
+  );
+};
+
+/** Where the descriptor lands unless the project says otherwise. */
+const defaultDescriptor = (projectRoot) =>
+  join('dist', projectRoot, 'descriptor.json');
+
+/**
+ * The media directory the project declares, for the target's inputs. A
+ * project that keeps its media somewhere else still has to invalidate the
+ * cache when it changes.
+ */
+const readDeclared = (projectRoot) => {
+  const dotKos = resolve(projectRoot, '.kos.json');
+  return existsSync(dotKos)
+    ? readJson(dotKos)?.kondra?.ui?.assets ?? {}
+    : {};
+};
+
+const mediaGlob = (declared) => mediaSource(declared).join('/');
+
+/**
+ * Write a detected media location into the project's .kos.json, so a project
+ * that keeps its media somewhere other than the ui default is wired up
+ * without having to be told where it is.
+ *
+ * Only what can be established is written: `mediaSrc` comes off the disk,
+ * and `mediaRoot` off a build output, which is exact where guessing from the
+ * source path would be wrong for any project that rewrites paths on the way
+ * out. Nothing already declared is touched.
+ */
+const detectLayout = (projectRoot, declared, outputDir) => {
+  const dotKos = resolve(projectRoot, '.kos.json');
+  if (!existsSync(dotKos)) {
+    return declared;
+  }
+
+  const found = { ...declared };
+  if (!found.mediaSrc) {
+    const detected = detectMediaSrc(projectRoot);
+    if (detected) {
+      found.mediaSrc = detected;
+      console.log(`kos-assets: found media in ${detected}`);
+    }
+  }
+  if (found.mediaSrc && found.mediaRoot === undefined) {
+    const root = detectMediaRoot(
+      projectRoot,
+      mediaSource(found),
+      resolve(outputDir)
+    );
+    if (root === undefined) {
+      console.warn(
+        `kos-assets: could not tell where ${found.mediaSrc} ends up inside ` +
+          `the kab — build the project and run init again, or set ` +
+          `kondra.ui.assets.mediaRoot in .kos.json`
+      );
+    } else {
+      found.mediaRoot = root;
+      console.log(`kos-assets: it is served from ${root || '/'} in the kab`);
+    }
+  }
+
+  if (found.mediaSrc === declared.mediaSrc &&
+      found.mediaRoot === declared.mediaRoot) {
+    return declared;
+  }
+
+  const kos = readJson(dotKos);
+  kos.kondra = {
+    ...kos.kondra,
+    ui: { ...kos.kondra?.ui, assets: { ...kos.kondra?.ui?.assets, ...found } },
+  };
+  writeJson(dotKos, kos);
+  console.log(`kos-assets: recorded the media location in ${dotKos}`);
+  return found;
+};
+
+/**
+ * Where the project's descriptor target writes, which is not always
+ * `dist/<projectRoot>` -- content projects in particular often point
+ * somewhere else, and the assets target has to follow it.
+ */
+const descriptorTarget = (project, projectRoot) => {
+  const options = project.targets?.descriptor?.options;
+  if (!options?.outputPath) {
+    return defaultDescriptor(projectRoot);
+  }
+  const dir = options.outputPath.replace('{projectRoot}', projectRoot);
+  return join(dir, options.fileName ?? 'descriptor.json');
+};
+
+const build = (projectRoot, out) => {
+  const descriptorPath = resolve(out ?? defaultDescriptor(projectRoot));
   if (!existsSync(descriptorPath)) {
     fail(
       `no descriptor at ${descriptorPath} — run the descriptor target first, or pass --out`
@@ -40,6 +161,8 @@ const build = (projectRoot, out) => {
     return;
   }
 
+  verifyContents(assets, dirname(descriptorPath));
+
   const descriptor = readJson(descriptorPath);
   descriptor.kondra = {
     ...descriptor.kondra,
@@ -81,17 +204,30 @@ const init = (projectRoot) => {
 
   const project = readJson(path);
   project.targets = project.targets ?? {};
+
+  // follow the project's own descriptor target rather than assuming where it
+  // writes, so a content project is wired correctly without a manual --out
+  const descriptor = descriptorTarget(project, projectRoot);
+  const out =
+    descriptor === defaultDescriptor(projectRoot) ? '' : ` --out ${descriptor}`;
+
+  const declared = detectLayout(
+    projectRoot,
+    readDeclared(projectRoot),
+    dirname(descriptor)
+  );
+
   // the declaration is written into a build output, so nx needs to know what
   // it reads and what it produces — otherwise a restored build can be paired
   // with a freshly scanned declaration and the kab ships a mismatch
   project.targets.assets = {
-    command: `${invocation()} build ${projectRoot}`,
+    command: `${invocation()} build ${projectRoot}${out}`,
     dependsOn: ['descriptor'],
     inputs: [
-      `{projectRoot}/${SOURCE_DIR.join('/')}/**/*`,
+      `{projectRoot}/${mediaGlob(declared)}/**/*`,
       '{projectRoot}/.kos.json',
     ],
-    outputs: ['{workspaceRoot}/dist/{projectRoot}/descriptor.json'],
+    outputs: [`{workspaceRoot}/${descriptor}`],
   };
 
   const zip = project.targets.zip;

package/bin/lib/declare-assets.mjs

@@ -12,6 +12,26 @@ import { join, resolve } from 'node:path';
 
 const SOURCE_DIR = ['src', 'assets', 'media'];
 const ASSETS_ROOT = '/assets/media';
+
+/**
+ * Where a project keeps its media, and where that media ends up inside the
+ * kab. They are two different things -- the project's build step decides the
+ * mapping between them, and a content project using vite's `publicDir` drops
+ * the directory name on the way out -- so neither can be derived from the
+ * other. A project that doesn't say gets the ui defaults.
+ *
+ *   "assets": { "mediaSrc": "assets/logos", "mediaRoot": "/logos" }
+ */
+const mediaSource = (declared) =>
+  declared.mediaSrc ? declared.mediaSrc.split('/').filter(Boolean) : SOURCE_DIR;
+
+const mediaRoot = (declared) => {
+  if (!declared.mediaRoot) {
+    return declared.mediaSrc ? '' : ASSETS_ROOT;
+  }
+  const trimmed = declared.mediaRoot.replace(/\/+$/, '');
+  return trimmed === '/' || trimmed === '' ? '' : `/${trimmed.replace(/^\/+/, '')}`;
+};
 const TYPES = {
   '.avif': 'image/avif',
   '.gif': 'image/gif',
@@ -243,6 +263,114 @@ const boundKey = (rel, bindings) => {
   return undefined;
 };
 
+/** Never a project's own media, and expensive to walk. */
+const SKIP_DIRS = new Set([
+  'node_modules',
+  'dist',
+  'tmp',
+  'coverage',
+  '.git',
+  '.nx',
+  '.kos',
+]);
+
+/** Every media file below a directory, by extension, with its path. */
+const scanMedia = (dir, prefix = '') =>
+  readdirSync(dir, { withFileTypes: true }).flatMap((item) => {
+    if (item.name.startsWith('.') || SKIP_DIRS.has(item.name)) return [];
+    const rel = prefix ? `${prefix}/${item.name}` : item.name;
+    if (item.isDirectory()) return scanMedia(join(dir, item.name), rel);
+    const ext = item.name.slice(item.name.lastIndexOf('.')).toLowerCase();
+    return TYPES[ext] ? [rel] : [];
+  });
+
+/** The deepest directory every one of these paths sits under. */
+const commonDir = (paths) => {
+  const segments = paths.map((path) => path.split('/').slice(0, -1));
+  const [first = [], ...rest] = segments;
+  let shared = first;
+  for (const other of rest) {
+    let i = 0;
+    while (i < shared.length && shared[i] === other[i]) i += 1;
+    shared = shared.slice(0, i);
+  }
+  return shared.join('/');
+};
+
+/** True when this directory holds media, or leads to some. */
+const holdsMedia = (dir) => scanMedia(dir).length > 0;
+
+/**
+ * The common ancestor of a project's media is too deep when the media
+ * happens to sit in one subfolder -- a brandset with a single brand would be
+ * read as that brand. So climb back up while the parent holds nothing but
+ * media, which stops at the directory the project actually treats as its
+ * media root: the one with something else beside it.
+ */
+const climbToMedia = (projectRoot, dir) => {
+  const segments = dir.split('/').filter(Boolean);
+  while (segments.length > 1) {
+    const parent = segments.slice(0, -1);
+    const entries = readdirSync(resolve(projectRoot, ...parent), {
+      withFileTypes: true,
+    }).filter(
+      (item) => !item.name.startsWith('.') && !SKIP_DIRS.has(item.name)
+    );
+    const onlyMedia = entries.every((item) =>
+      item.isDirectory()
+        ? holdsMedia(resolve(projectRoot, ...parent, item.name))
+        : TYPES[item.name.slice(item.name.lastIndexOf('.')).toLowerCase()]
+    );
+    if (!onlyMedia) {
+      break;
+    }
+    segments.pop();
+  }
+  return segments.join('/');
+};
+
+/**
+ * Where a project already keeps its media, for a project that hasn't said.
+ * Returns undefined when it is already in the ui default place, or when
+ * there is no media to find.
+ */
+const detectMediaSrc = (projectRoot) => {
+  if (existsSync(resolve(projectRoot, ...SOURCE_DIR))) {
+    return undefined;
+  }
+  const found = scanMedia(resolve(projectRoot));
+  if (found.length === 0) {
+    return undefined;
+  }
+  const dir = commonDir(found);
+  return dir === '' ? undefined : climbToMedia(projectRoot, dir);
+};
+
+/**
+ * Where a media directory ends up inside the kab, read off a build output
+ * rather than guessed: find a file the build already copied and take the
+ * path it was copied to. Undefined when the project hasn't been built, or
+ * when the build doesn't carry the media at all.
+ */
+const detectMediaRoot = (projectRoot, source, outputDir) => {
+  const mediaDir = resolve(projectRoot, ...source);
+  if (!existsSync(mediaDir) || !existsSync(outputDir)) {
+    return undefined;
+  }
+  const [sample] = scanMedia(mediaDir);
+  if (!sample) {
+    return undefined;
+  }
+  const built = scanMedia(resolve(outputDir)).filter(
+    (path) => path === sample || path.endsWith(`/${sample}`)
+  );
+  if (built.length !== 1) {
+    return undefined;
+  }
+  const root = built[0].slice(0, built[0].length - sample.length);
+  return root === '' ? '' : `/${root.replace(/\/+$/, '')}`;
+};
+
 const fail = (message) => {
   console.error(`kos-assets: ${message}`);
   process.exit(1);
@@ -269,16 +397,22 @@ const walk = (dir, prefix = '') =>
  * groups and preload flags are authored in .kos.json and carried through.
  */
 const buildAssets = (projectRoot) => {
-  const mediaDir = resolve(projectRoot, ...SOURCE_DIR);
-  if (!existsSync(mediaDir)) {
-    return undefined;
-  }
-
   const dotKos = resolve(projectRoot, '.kos.json');
   const declared = existsSync(dotKos)
     ? readJson(dotKos)?.kondra?.ui?.assets ?? {}
     : {};
 
+  const source = mediaSource(declared);
+  const mediaDir = resolve(projectRoot, ...source);
+  if (!existsSync(mediaDir)) {
+    // a project that named its media directory meant it, so a typo there is
+    // a build error rather than a project that quietly declares nothing
+    if (declared.mediaSrc) {
+      fail(`no media directory at ${join(projectRoot, ...source)} (mediaSrc)`);
+    }
+    return undefined;
+  }
+
   const bindings = declared.keys ?? {};
   const markers = readMarkers(mediaDir);
   const claimed = new Set();
@@ -379,7 +513,7 @@ const buildAssets = (projectRoot) => {
   }
 
   return {
-    root: ASSETS_ROOT,
+    root: mediaRoot(declared),
     entries,
     ...(Object.keys(groups).length > 0 ? { groups } : {}),
   };
@@ -390,6 +524,13 @@ export {
   SOURCE_DIR,
   ASSETS_ROOT,
   TYPES,
+  mediaSource,
+  mediaRoot,
+  scanMedia,
+  commonDir,
+  climbToMedia,
+  detectMediaSrc,
+  detectMediaRoot,
   parseMarker,
   readMarkers,
   bindingMatcher,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kosdev-code/kos-asset-manager",
-  "version": "0.0.1-next.29",
+  "version": "0.0.1-next.30",
   "type": "module",
   "main": "./index.js",
   "types": "./index.d.ts",
@@ -25,7 +25,7 @@
   },
   "kos": {
     "build": {
-      "gitHash": "1b2fc996563150e3da055a9506a28b7cb132c060"
+      "gitHash": "630400cd67fd24b5cd069b7661dae83277c18934"
     }
   },
   "publishConfig": {