@colixsystems/widget-sdk 0.197.0 → 0.199.0

package/dist/bundled-assets.js

@@ -0,0 +1,239 @@
+// The files a widget package ships in its assets/ directory: which names and
+// types are allowed. Pure and filesystem-free, so the CLI, the dev server, the
+// first-party packer and the backend all apply one rule set.
+// Keep bundled-assets.cjs in lockstep.
+
+import { CONTRACT } from "./contract.js";
+
+const RULES = CONTRACT.bundledAssets;
+const BUNDLED_ASSET_DIRECTORY = RULES.directory;
+const ALLOWED_EXTENSIONS = Object.values(RULES.types).flatMap(
+  (type) => type.extensions,
+);
+const NAME_RE = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+
+const PNG = { kind: "image", mimeType: "image/png", extensions: ["png"] };
+const JPEG = { kind: "image", mimeType: "image/jpeg", extensions: ["jpg", "jpeg"] };
+const GIF = { kind: "image", mimeType: "image/gif", extensions: ["gif"] };
+const WEBP = { kind: "image", mimeType: "image/webp", extensions: ["webp"] };
+const WAV = { kind: "audio", mimeType: "audio/wav", extensions: ["wav"] };
+const MP3 = { kind: "audio", mimeType: "audio/mpeg", extensions: ["mp3"] };
+const M4A = { kind: "audio", mimeType: "audio/mp4", extensions: ["m4a"] };
+
+const PNG_SIGNATURE = [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a];
+const JPEG_SIGNATURE = [0xff, 0xd8, 0xff];
+const M4A_BRANDS = ["M4A ", "M4B ", "mp42", "isom", "mp41"];
+
+function _hasBytes(bytes, signature, offset) {
+  if (bytes.length < offset + signature.length) return false;
+  return signature.every((byte, i) => bytes[offset + i] === byte);
+}
+
+function _hasText(bytes, text, offset) {
+  return _hasBytes(bytes, Array.from(text, (ch) => ch.charCodeAt(0)), offset);
+}
+
+// kbps by bitrate index; index 0 (free format) and 15 are never accepted.
+const MPEG_BITRATES = {
+  v1Layer1: [0, 32, 64, 96, 128, 160, 192, 224, 256, 288, 320, 352, 384, 416, 448],
+  v1Layer2: [0, 32, 48, 56, 64, 80, 96, 112, 128, 160, 192, 224, 256, 320, 384],
+  v1Layer3: [0, 32, 40, 48, 56, 64, 80, 96, 112, 128, 160, 192, 224, 256, 320],
+  v2Layer1: [0, 32, 48, 56, 64, 80, 96, 112, 128, 144, 160, 176, 192, 224, 256],
+  v2Layer2or3: [0, 8, 16, 24, 32, 40, 48, 56, 64, 80, 96, 112, 128, 144, 160],
+};
+// Hz by the header's version bits (3 = MPEG-1, 2 = MPEG-2, 0 = MPEG-2.5).
+const MPEG_SAMPLE_RATES = {
+  3: [44100, 48000, 32000],
+  2: [22050, 24000, 16000],
+  0: [11025, 12000, 8000],
+};
+const MPEG_LAYER_1 = 3;
+const MPEG_LAYER_3 = 1;
+
+function _mpegBitrateTable(isVersion1, layer) {
+  if (layer === MPEG_LAYER_1) return isVersion1 ? MPEG_BITRATES.v1Layer1 : MPEG_BITRATES.v2Layer1;
+  if (!isVersion1) return MPEG_BITRATES.v2Layer2or3;
+  return layer === MPEG_LAYER_3 ? MPEG_BITRATES.v1Layer3 : MPEG_BITRATES.v1Layer2;
+}
+
+/** Byte length of the MPEG audio frame whose header starts at `offset`, or 0. */
+function _mpegFrameLength(bytes, offset) {
+  if (bytes.length < offset + 4) return 0;
+  if (bytes[offset] !== 0xff || (bytes[offset + 1] & 0xe0) !== 0xe0) return 0;
+  const version = (bytes[offset + 1] >> 3) & 3;
+  const layer = (bytes[offset + 1] >> 1) & 3;
+  const bitrateIndex = bytes[offset + 2] >> 4;
+  const sampleRateIndex = (bytes[offset + 2] >> 2) & 3;
+  const padding = (bytes[offset + 2] >> 1) & 1;
+  if (version === 1 || layer === 0 || sampleRateIndex === 3) return 0;
+  if (bitrateIndex === 0 || bitrateIndex === 15) return 0;
+  const isVersion1 = version === 3;
+  const bitrate = _mpegBitrateTable(isVersion1, layer)[bitrateIndex] * 1000;
+  const sampleRate = MPEG_SAMPLE_RATES[version][sampleRateIndex];
+  if (layer === MPEG_LAYER_1) return (Math.floor((12 * bitrate) / sampleRate) + padding) * 4;
+  const samplesPerByte = layer === MPEG_LAYER_3 && !isVersion1 ? 72 : 144;
+  return Math.floor((samplesPerByte * bitrate) / sampleRate) + padding;
+}
+
+// A two-byte sync alone matches a UTF-16 BOM, so a second frame must follow.
+function _isMpegAudioAt(bytes, offset) {
+  const length = _mpegFrameLength(bytes, offset);
+  if (length === 0) return false;
+  const next = offset + length;
+  return next === bytes.length || _mpegFrameLength(bytes, next) > 0;
+}
+
+const ID3_HEADER_BYTES = 10;
+
+function _isMp3(bytes) {
+  if (!_hasText(bytes, "ID3", 0)) return _isMpegAudioAt(bytes, 0);
+  if (bytes.length < ID3_HEADER_BYTES || bytes[3] === 0xff || bytes[4] === 0xff) return false;
+  const size = [bytes[6], bytes[7], bytes[8], bytes[9]];
+  if (size.some((byte) => byte >= 0x80)) return false;
+  const tagBytes = (size[0] << 21) | (size[1] << 14) | (size[2] << 7) | size[3];
+  const footerBytes = bytes[5] & 0x10 ? ID3_HEADER_BYTES : 0;
+  return _isMpegAudioAt(bytes, ID3_HEADER_BYTES + tagBytes + footerBytes);
+}
+
+function _describe(type) {
+  return { kind: type.kind, mimeType: type.mimeType, extensions: [...type.extensions] };
+}
+
+function _sniff(bytes) {
+  if (_hasBytes(bytes, PNG_SIGNATURE, 0)) return PNG;
+  if (_hasBytes(bytes, JPEG_SIGNATURE, 0)) return JPEG;
+  if (_hasText(bytes, "GIF87a", 0) || _hasText(bytes, "GIF89a", 0)) return GIF;
+  if (_hasText(bytes, "RIFF", 0)) {
+    if (_hasText(bytes, "WEBP", 8)) return WEBP;
+    if (_hasText(bytes, "WAVE", 8)) return WAV;
+    return null;
+  }
+  if (_hasText(bytes, "ftyp", 4)) {
+    return M4A_BRANDS.some((brand) => _hasText(bytes, brand, 8)) ? M4A : null;
+  }
+  if (_isMp3(bytes)) return MP3;
+  return null;
+}
+
+/**
+ * Identify a bundled file from its leading bytes alone.
+ * Returns `{ kind: "image" | "audio", mimeType, extensions }`, or `null` when
+ * the bytes are not one of the bundled types.
+ */
+function sniffBundledAssetType(bytes) {
+  if (!bytes || typeof bytes.length !== "number") return null;
+  const type = _sniff(bytes);
+  return type ? _describe(type) : null;
+}
+
+function _extensionOf(name) {
+  const dot = name.lastIndexOf(".");
+  return dot === -1 ? "" : name.slice(dot + 1).toLowerCase();
+}
+
+function _isWellFormedName(name) {
+  return (
+    typeof name === "string" &&
+    name.length <= RULES.maxNameLength &&
+    NAME_RE.test(name) &&
+    !name.includes("..")
+  );
+}
+
+/** True when `name` may be used as a file name inside a package's assets/. */
+function isValidBundledAssetName(name) {
+  return _isWellFormedName(name) && ALLOWED_EXTENSIONS.includes(_extensionOf(name));
+}
+
+function _extensionList() {
+  const last = ALLOWED_EXTENSIONS[ALLOWED_EXTENSIONS.length - 1];
+  return `${ALLOWED_EXTENSIONS.slice(0, -1).join(", ")} and ${last}`;
+}
+
+function _error(code, name, rule) {
+  const where = `${BUNDLED_ASSET_DIRECTORY}/${name === null ? "" : name}`;
+  return { code, name, message: `${where}: ${rule}` };
+}
+
+function _fileError(file, seenNames) {
+  const { name, bytes } = file;
+  if (!_isWellFormedName(name)) {
+    return _error(
+      "ASSET_NAME_INVALID",
+      typeof name === "string" ? name : String(name),
+      "a bundled file name starts with a letter or digit, uses only letters, " +
+        `digits, dots, hyphens and underscores, and is at most ${RULES.maxNameLength} ` +
+        "characters long. Subdirectories are not allowed.",
+    );
+  }
+  const extension = _extensionOf(name);
+  if (!ALLOWED_EXTENSIONS.includes(extension)) {
+    return _error(
+      "ASSET_TYPE_NOT_ALLOWED",
+      name,
+      `only ${_extensionList()} files can be bundled.`,
+    );
+  }
+  if (seenNames.has(name.toLowerCase())) {
+    return _error(
+      "ASSET_NAME_DUPLICATE",
+      name,
+      "another bundled file has the same name when upper and lower case are ignored.",
+    );
+  }
+  seenNames.add(name.toLowerCase());
+  if (!bytes || !bytes.length) {
+    return _error("ASSET_EMPTY", name, "the file is empty.");
+  }
+  const sniffed = _sniff(bytes);
+  if (!sniffed || !sniffed.extensions.includes(extension)) {
+    return _error(
+      "ASSET_CONTENT_MISMATCH",
+      name,
+      `the file's content is not a valid .${extension} file.`,
+    );
+  }
+  return null;
+}
+
+/**
+ * Validate the files of a package's assets/ directory.
+ * `files` is `[{ name, bytes }]`. Returns `{ ok, errors, assets }` where each
+ * error is `{ code, name, message }` and each accepted asset is
+ * `{ name, kind, mimeType, sizeBytes }`, sorted by name.
+ * Error codes: ASSET_NAME_INVALID, ASSET_TYPE_NOT_ALLOWED, ASSET_EMPTY,
+ * ASSET_CONTENT_MISMATCH, ASSET_NAME_DUPLICATE, ASSET_TOO_MANY.
+ */
+function validateBundledAssets(files) {
+  const list = Array.isArray(files) ? files : [];
+  const errors = [];
+  const assets = [];
+  const seenNames = new Set();
+  if (list.length > RULES.maxFiles) {
+    errors.push(
+      _error(
+        "ASSET_TOO_MANY",
+        null,
+        `a package can bundle at most ${RULES.maxFiles} files; this one has ${list.length}.`,
+      ),
+    );
+  }
+  for (const file of list) {
+    const error = _fileError(file || {}, seenNames);
+    if (error) {
+      errors.push(error);
+      continue;
+    }
+    const { kind, mimeType } = _sniff(file.bytes);
+    assets.push({ name: file.name, kind, mimeType, sizeBytes: file.bytes.length });
+  }
+  assets.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+  return { ok: errors.length === 0, errors, assets };
+}
+
+export {
+  BUNDLED_ASSET_DIRECTORY,
+  isValidBundledAssetName,
+  sniffBundledAssetType,
+  validateBundledAssets,
+};

package/dist/cli.js

@@ -5,7 +5,7 @@
 //                                                          — REQ-WSDK-DEVKIT local dev server
 
 import { readFileSync } from "node:fs";
-import { basename, resolve } from "node:path";
+import { basename, dirname, resolve } from "node:path";
 import { pathToFileURL } from "node:url";
 import { argv, exit, stderr, stdout } from "node:process";
 import {
@@ -15,6 +15,10 @@ import {
   narrowManifestForFile,
 } from "./linter.js";
 import { startDevServer } from "./devserver.js";
+import {
+  bundledAssetDirectoryOf,
+  loadBundledAssets,
+} from "./bundled-assets-fs.js";
 
 function usage() {
   stderr.write(
@@ -22,6 +26,8 @@ function usage() {
       "  appstudio-widget lint <file.jsx...> [--manifest <path>]\n" +
       "    Pass every file the widget ships plus --manifest to also check " +
       "that each styleSchema field is actually read.\n" +
+      "    An assets/ directory beside a file is checked too: every image " +
+      "and sound in it must be a type the package may bundle.\n" +
       "  appstudio-widget dev <entry.jsx|widget-dir> [--port <n>] [--manifest <path>]\n" +
       "    A directory containing widget.json runs in multi-file mode " +
       "(REQ-WSDK-DEVKIT v2): the dev server reads the canonical web entry, " +
@@ -57,6 +63,28 @@ function parseFlags(args) {
   return { flags, positionals };
 }
 
+// One read per assets/ directory, however many linted files sit beside it.
+function loadAssetsBesideFiles(filePaths) {
+  const byDirectory = new Map();
+  for (const filePath of filePaths) {
+    const assetsDir = bundledAssetDirectoryOf(dirname(filePath));
+    if (!byDirectory.has(assetsDir)) {
+      byDirectory.set(assetsDir, loadBundledAssets(assetsDir));
+    }
+  }
+  return byDirectory;
+}
+
+function assetFindings(assets) {
+  return assets.errors.map((error) => ({
+    rule: error.code,
+    severity: "error",
+    label: error.message,
+    line: 0,
+    snippet: "",
+  }));
+}
+
 async function loadManifest(path) {
   const abs = resolve(path);
   if (abs.endsWith(".json")) return JSON.parse(readFileSync(abs, "utf8"));
@@ -68,9 +96,8 @@ function writeFindings(findings, stream) {
   for (const f of findings) {
     const severity = f.severity === "warning" ? "warning" : "error";
     const where = f.line ? ` line ${f.line}` : "";
-    stream.write(
-      `  ${severity} [${f.rule}]${where}: ${f.label}\n    ${f.snippet}\n`,
-    );
+    const snippet = f.snippet ? `    ${f.snippet}\n` : "";
+    stream.write(`  ${severity} [${f.rule}]${where}: ${f.label}\n${snippet}`);
   }
 }
 
@@ -104,16 +131,20 @@ async function runLint(rest) {
     }
   }
   const label = positionals.join(", ");
+  const assetsByDirectory = loadAssetsBesideFiles(Object.keys(files));
+  const assetsBeside = (filePath) =>
+    assetsByDirectory.get(bundledAssetDirectoryOf(dirname(filePath)));
   // Narrow per split-impl file, as the submission gate does.
   const perFile = Object.entries(files).map(([filePath, source]) => [
     filePath,
-    lintSource(
-      source,
-      manifest
+    lintSource(source, {
+      assetFiles: assetsBeside(filePath).fileNames,
+      ...(manifest
         ? { manifest: narrowManifestForFile(manifest, basename(filePath)) }
-        : undefined,
-    ),
+        : {}),
+    }),
   ]);
+  const bundled = [...assetsByDirectory.values()].flatMap(assetFindings);
   const wiring = manifest
     ? lintStyleWiring(manifest, files)
     : { ok: true, findings: [] };
@@ -123,6 +154,7 @@ async function runLint(rest) {
     : { ok: true, findings: [] };
   const all = perFile
     .flatMap(([, r]) => r.findings)
+    .concat(bundled)
     .concat(wiring.findings)
     .concat(editability.findings);
   if (all.length === 0) {
@@ -132,7 +164,11 @@ async function runLint(rest) {
   // sc-3493 — a warning-severity finding used to be swallowed: `ok` stays true
   // for warnings, so the CLI printed "clean" and dropped them. A warning nobody
   // sees is pointless. Report every finding; only errors change the exit code.
-  const ok = perFile.every(([, r]) => r.ok) && wiring.ok && editability.ok;
+  const ok =
+    perFile.every(([, r]) => r.ok) &&
+    bundled.length === 0 &&
+    wiring.ok &&
+    editability.ok;
   const errors = all.filter((f) => f.severity !== "warning").length;
   const stream = ok ? stdout : stderr;
   stream.write(
@@ -143,6 +179,10 @@ async function runLint(rest) {
     if (perFile.length > 1) stream.write(`${filePath}:\n`);
     writeFindings(r.findings, stream);
   }
+  if (bundled.length > 0) {
+    stream.write("assets:\n");
+    writeFindings(bundled, stream);
+  }
   if (wiring.findings.length > 0) {
     stream.write(`manifest.styleSchema:\n`);
     writeFindings(wiring.findings, stream);
@@ -185,7 +225,8 @@ async function runDev(rest) {
       `  manifest: ${handle.url}/manifest.json\n` +
       `  reload:   ${handle.url}/__dev/events (SSE)\n` +
       (handle.directoryMode
-        ? `  files:    ${handle.url}/file/<relpath>\n  shims:    ${handle.url}/shim/<slug>\n`
+        ? `  files:    ${handle.url}/file/<relpath>\n  shims:    ${handle.url}/shim/<slug>\n` +
+          `  assets:   ${handle.url}/assets/<name>\n`
         : "") +
       (handle.manifestId ? `  id:       ${handle.manifestId}\n` : "") +
       `\nIn the Studio Builder (dev mode), open the "Dev widgets" panel and add:\n` +