@utilix-tech/sdk 0.7.0 → 0.8.0

package/CHANGELOG.md

@@ -2,11 +2,26 @@
 
 Full release notes for all Utilix surfaces (browser tools, REST API, SDKs, MCP server) live at [utilix.tech/changelog](https://utilix.tech/changelog). This file tracks just this package.
 
-## 0.3.1
-- Metadata fixes: corrected repository/bug tracker links, updated tool count in the package description.
+## 0.8.0
+- Added ID3 Tag Reader and .env.example Diff Checker.
+
+## 0.7.0
+- Added WAV Audio Info and Readability Score Calculator.
+
+## 0.6.0
+- Added EXIF Viewer and Commit Message Generator (AI).
+
+## 0.5.0
+- Added PDF Metadata Reader and JWK Viewer.
+
+## 0.4.1
+- Added HAR File Viewer and NDJSON Formatter/Validator.
+
+## 0.4.0
+- Metadata fixes: corrected repository/bug tracker links, updated the stale dependency, added missing package files.
 
 ## 0.3.0
-- Added the `media` module.
+- Added the `media` module (Passive Voice Detector, Image Info).
 
 ## 0.2.0
 - 400+ functions across 14 modules, including the `ai_agent` module for LLM/RAG pipelines.

package/README.md

@@ -156,12 +156,12 @@ scoreReadability("The cat sat on the mat. It was a sunny day.");
 
 ---
 
-### `/data`: CSV / YAML / TOML / XML / INI / NDJSON
+### `/data`: CSV / YAML / TOML / XML / INI / NDJSON / .env diff
 
 ```ts
 import { parseCsv, csvToJson, validateYaml, tomlToJson, jsonToToml,
          formatXml, xmlToJson, jsonToXml, parseIni,
-         validateNdjson, formatNdjson, ndjsonToJsonArray } from "@utilix-tech/sdk/data";
+         validateNdjson, formatNdjson, ndjsonToJsonArray, diffEnvExample } from "@utilix-tech/sdk/data";
 
 // CSV
 const rows = parseCsv("name,age\nalice,30\nbob,25");
@@ -185,6 +185,10 @@ parseIni("[db]\nhost=localhost\nport=5432");
 validateNdjson('{"id":1}\n{"id":2}');       // { valid: true, totalLines: 2, ... }
 formatNdjson('{"id":1}');                    // '{\n  "id": 1\n}'
 ndjsonToJsonArray('{"id":1}\n{"id":2}');     // '[\n  { "id": 1 },\n  { "id": 2 }\n]'
+
+// Diff a .env file against its .env.example template
+diffEnvExample("FOO=1\nBAR=2", "FOO=\nBAR=y\nBAZ=z");
+// { missingInExample: [], missingInEnv: ["BAZ"], emptyValueInExample: ["FOO"], keysInBoth: 2 }
 ```
 
 ---
@@ -420,10 +424,10 @@ analyzeString("café");          // { length: 4, codePoints: [...], ... }
 
 ---
 
-### `/media`: Image Header Parsing, EXIF, PDF & WAV Metadata
+### `/media`: Image Header Parsing, EXIF, PDF, WAV & ID3 Metadata
 
 ```ts
-import { readImageInfo, readExifData, readPdfMetadata, readWavInfo } from "@utilix-tech/sdk/media";
+import { readImageInfo, readExifData, readPdfMetadata, readWavInfo, readId3Tags } from "@utilix-tech/sdk/media";
 
 // Reads format, dimensions, bit depth, and alpha channel straight from
 // file bytes: no decoding, no canvas, no image library.
@@ -448,9 +452,16 @@ readPdfMetadata(new Uint8Array(pdfBytes));
 const wavBytes = await fs.promises.readFile("recording.wav");
 readWavInfo(new Uint8Array(wavBytes));
 // { audioFormat: 1, audioFormatLabel: "PCM", channels: 2, sampleRate: 44100, bitsPerSample: 16, durationSeconds: 12.4, ... }
+
+// Reads title, artist, album, year, genre, comment, and track number from
+// an MP3's ID3 tags. Prefers ID3v2.3/2.4 text frames, falls back to the
+// classic 128-byte ID3v1/1.1 trailer.
+const mp3Bytes = await fs.promises.readFile("track.mp3");
+readId3Tags(new Uint8Array(mp3Bytes));
+// { version: "ID3v2.3.0", title: "Track Name", artist: "Artist Name", genre: "Rock", ... }
 ```
 
-`readImageInfo` supports PNG, JPEG, GIF, WebP, and BMP. `readExifData` supports JPEG only. `readWavInfo` supports the canonical RIFF/WAVE container only.
+`readImageInfo` supports PNG, JPEG, GIF, WebP, and BMP. `readExifData` supports JPEG only. `readWavInfo` supports the canonical RIFF/WAVE container only. `readId3Tags` decodes ID3v2.3/2.4 and ID3v1/1.1 only (ID3v2.2 is detected but not decoded).
 
 ---
 

package/dist/{chunk-5CKOJXFU.js → chunk-GUUYEIU6.js}

@@ -4,6 +4,7 @@ import { __export } from './chunk-MLKGABMK.js';
 var media_exports = {};
 __export(media_exports, {
   readExifData: () => readExifData,
+  readId3Tags: () => readId3Tags,
   readImageInfo: () => readImageInfo,
   readPdfMetadata: () => readPdfMetadata,
   readWavInfo: () => readWavInfo
@@ -520,5 +521,214 @@ function readWavInfo(bytes) {
     fileSize
   };
 }
+var ID3V1_GENRES = [
+  "Blues",
+  "Classic Rock",
+  "Country",
+  "Dance",
+  "Disco",
+  "Funk",
+  "Grunge",
+  "Hip-Hop",
+  "Jazz",
+  "Metal",
+  "New Age",
+  "Oldies",
+  "Other",
+  "Pop",
+  "R&B",
+  "Rap",
+  "Reggae",
+  "Rock",
+  "Techno",
+  "Industrial",
+  "Alternative",
+  "Ska",
+  "Death Metal",
+  "Pranks",
+  "Soundtrack",
+  "Euro-Techno",
+  "Ambient",
+  "Trip-Hop",
+  "Vocal",
+  "Jazz+Funk",
+  "Fusion",
+  "Trance",
+  "Classical",
+  "Instrumental",
+  "Acid",
+  "House",
+  "Game",
+  "Sound Clip",
+  "Gospel",
+  "Noise",
+  "AlternRock",
+  "Bass",
+  "Soul",
+  "Punk",
+  "Space",
+  "Meditative",
+  "Instrumental Pop",
+  "Instrumental Rock",
+  "Ethnic",
+  "Gothic",
+  "Darkwave",
+  "Techno-Industrial",
+  "Electronic",
+  "Pop-Folk",
+  "Eurodance",
+  "Dream",
+  "Southern Rock",
+  "Comedy",
+  "Cult",
+  "Gangsta",
+  "Top 40",
+  "Christian Rap",
+  "Pop/Funk",
+  "Jungle",
+  "Native American",
+  "Cabaret",
+  "New Wave",
+  "Psychedelic",
+  "Rave",
+  "Showtunes",
+  "Trailer",
+  "Lo-Fi",
+  "Tribal",
+  "Acid Punk",
+  "Acid Jazz",
+  "Polka",
+  "Retro",
+  "Musical",
+  "Rock & Roll",
+  "Hard Rock"
+];
+function readSynchsafeUInt32(bytes, offset) {
+  return (bytes[offset] & 127) << 21 | (bytes[offset + 1] & 127) << 14 | (bytes[offset + 2] & 127) << 7 | bytes[offset + 3] & 127;
+}
+function readUInt32BE(bytes, offset) {
+  return (bytes[offset] << 24 | bytes[offset + 1] << 16 | bytes[offset + 2] << 8 | bytes[offset + 3]) >>> 0;
+}
+function decodeId3Text(frameBytes) {
+  if (frameBytes.length === 0) return "";
+  const encodingByte = frameBytes[0];
+  const content = frameBytes.subarray(1);
+  let out = "";
+  if (encodingByte === 3) {
+    out = Buffer.from(content).toString("utf8");
+  } else if (encodingByte === 1 || encodingByte === 2) {
+    let little = encodingByte === 1;
+    let start = 0;
+    if (encodingByte === 1 && content.length >= 2) {
+      if (content[0] === 255 && content[1] === 254) {
+        little = true;
+        start = 2;
+      } else if (content[0] === 254 && content[1] === 255) {
+        little = false;
+        start = 2;
+      }
+    }
+    for (let i = start; i + 1 < content.length; i += 2) {
+      const code = little ? content[i] | content[i + 1] << 8 : content[i] << 8 | content[i + 1];
+      if (code === 0) break;
+      out += String.fromCharCode(code);
+    }
+  } else {
+    for (const b of content) {
+      if (b === 0) break;
+      out += String.fromCharCode(b);
+    }
+  }
+  return out.replace(/\0+$/, "").trim();
+}
+function readId3v2(bytes) {
+  if (bytes.length < 10 || bytes[0] !== 73 || bytes[1] !== 68 || bytes[2] !== 51) return null;
+  const majorVersion = bytes[3];
+  const revision = bytes[4];
+  const tagSize = readSynchsafeUInt32(bytes, 6);
+  const version = `ID3v2.${majorVersion}.${revision}`;
+  if (majorVersion !== 3 && majorVersion !== 4) {
+    return { version, frames: {}, frameCount: 0 };
+  }
+  const frames = {};
+  let offset = 10;
+  const end = Math.min(10 + tagSize, bytes.length);
+  let frameCount = 0;
+  while (offset + 10 <= end) {
+    const frameId = String.fromCharCode(bytes[offset], bytes[offset + 1], bytes[offset + 2], bytes[offset + 3]);
+    if (frameId === "\0\0\0\0") break;
+    const frameSize = majorVersion === 4 ? readSynchsafeUInt32(bytes, offset + 4) : readUInt32BE(bytes, offset + 4);
+    const frameStart = offset + 10;
+    if (frameSize <= 0 || frameStart + frameSize > bytes.length) break;
+    const frameBytes = bytes.subarray(frameStart, frameStart + frameSize);
+    if (frameId[0] === "T" && frameId !== "TXXX") {
+      frames[frameId] = decodeId3Text(frameBytes);
+    } else if (frameId === "COMM" && frameBytes.length > 4) {
+      const rebuilt = new Uint8Array(frameBytes.length - 3);
+      rebuilt[0] = frameBytes[0];
+      rebuilt.set(frameBytes.subarray(4), 1);
+      const decoded = decodeId3Text(rebuilt);
+      const parts = decoded.split("\0");
+      frames["COMM"] = (parts[parts.length - 1] || decoded).trim();
+    }
+    frameCount++;
+    offset = frameStart + frameSize;
+  }
+  return { version, frames, frameCount };
+}
+function readId3v1(bytes) {
+  if (bytes.length < 128) return null;
+  const start = bytes.length - 128;
+  if (String.fromCharCode(bytes[start], bytes[start + 1], bytes[start + 2]) !== "TAG") return null;
+  const readField = (offset, length) => {
+    let s = "";
+    for (let i = 0; i < length; i++) {
+      const b = bytes[start + offset + i];
+      if (b === 0) break;
+      s += String.fromCharCode(b);
+    }
+    return s.trim();
+  };
+  const title = readField(3, 30);
+  const artist = readField(33, 30);
+  const album = readField(63, 30);
+  const year = readField(93, 4);
+  const isV11 = bytes[start + 125] === 0 && bytes[start + 126] !== 0;
+  const comment = readField(97, isV11 ? 28 : 30);
+  const genreIndex = bytes[start + 127];
+  const genre = ID3V1_GENRES[genreIndex] ?? `Unknown (${genreIndex})`;
+  const result = { genre };
+  if (title) result.title = title;
+  if (artist) result.artist = artist;
+  if (album) result.album = album;
+  if (year) result.year = year;
+  if (comment) result.comment = comment;
+  if (isV11) result.trackNumber = String(bytes[start + 126]);
+  return result;
+}
+function readId3Tags(bytes) {
+  const v2 = readId3v2(bytes);
+  const v1 = readId3v1(bytes);
+  if (v2 && Object.keys(v2.frames).length > 0) {
+    const f = v2.frames;
+    const result = { version: v2.version, frameCount: v2.frameCount };
+    if (f["TIT2"]) result.title = f["TIT2"];
+    if (f["TPE1"]) result.artist = f["TPE1"];
+    if (f["TALB"]) result.album = f["TALB"];
+    const year = f["TYER"] || f["TDRC"];
+    if (year) result.year = year;
+    if (f["TCON"]) result.genre = f["TCON"];
+    if (f["COMM"]) result.comment = f["COMM"];
+    if (f["TRCK"]) result.trackNumber = f["TRCK"];
+    return result;
+  }
+  if (v1) {
+    return { version: v1.trackNumber !== void 0 ? "ID3v1.1" : "ID3v1", ...v1 };
+  }
+  if (v2) {
+    return { error: `Unsupported ID3 tag version: ${v2.version} (only ID3v2.3, ID3v2.4, and ID3v1/1.1 are supported)` };
+  }
+  return { error: "No ID3v1 or ID3v2.3/2.4 tags found in this file" };
+}
 
-export { media_exports, readExifData, readImageInfo, readPdfMetadata, readWavInfo };
+export { media_exports, readExifData, readId3Tags, readImageInfo, readPdfMetadata, readWavInfo };

package/dist/{chunk-DNCOIO5N.js → chunk-TINQFTLO.js}

@@ -7,6 +7,7 @@ var data_exports = {};
 __export(data_exports, {
   csvToJson: () => csvToJson,
   detectDelimiter: () => detectDelimiter,
+  diffEnvExample: () => diffEnvExample,
   envToExport: () => envToExport,
   envToJson: () => envToJson,
   formatNdjson: () => formatNdjson,
@@ -1081,6 +1082,23 @@ function envToExport(input) {
 function validateEnvKey(key) {
   return /^[A-Za-z_][A-Za-z0-9_]*$/.test(key);
 }
+function diffEnvExample(envInput, exampleInput) {
+  const envParsed = parseEnv(envInput);
+  if (envParsed.errors.length > 0) {
+    return { error: `.env: ${envParsed.errors.map((e) => `Line ${e.line}: ${e.message}`).join("; ")}` };
+  }
+  const exampleParsed = parseEnv(exampleInput);
+  if (exampleParsed.errors.length > 0) {
+    return { error: `.env.example: ${exampleParsed.errors.map((e) => `Line ${e.line}: ${e.message}`).join("; ")}` };
+  }
+  const envKeys = new Set(envParsed.entries.map((e) => e.key));
+  const exampleValues = new Map(exampleParsed.entries.map((e) => [e.key, e.value]));
+  const missingInExample = [...envKeys].filter((k) => !exampleValues.has(k)).sort();
+  const missingInEnv = [...exampleValues.keys()].filter((k) => !envKeys.has(k)).sort();
+  const emptyValueInExample = [...exampleValues.entries()].filter(([k, v]) => envKeys.has(k) && v === "").map(([k]) => k).sort();
+  const keysInBoth = [...envKeys].filter((k) => exampleValues.has(k)).length;
+  return { missingInExample, missingInEnv, emptyValueInExample, keysInBoth };
+}
 function validateNdjson(input) {
   const rawLines = input.split("\n");
   const lines = [];
@@ -1140,4 +1158,4 @@ function jsonArrayToNdjson(input) {
   return parsed.map((item) => JSON.stringify(item)).join("\n");
 }
 
-export { csvToJson, data_exports, detectDelimiter, envToExport, envToJson, formatNdjson, formatToml, formatXml, getSection, getSectionNames, getTomlStats, getXmlStats, getYamlStats, iniToJson, jsonArrayToNdjson, jsonToIni, jsonToToml, jsonToXml, minifyNdjson, minifyToml, minifyXml, ndjsonToJsonArray, parseCsv, parseEnv, parseIni, parseXmlToObject, stringifyIni, toCsvString, tomlToJson, validateEnvKey, validateIni, validateNdjson, validateToml, validateXml, validateYaml, xmlToJson };
+export { csvToJson, data_exports, detectDelimiter, diffEnvExample, envToExport, envToJson, formatNdjson, formatToml, formatXml, getSection, getSectionNames, getTomlStats, getXmlStats, getYamlStats, iniToJson, jsonArrayToNdjson, jsonToIni, jsonToToml, jsonToXml, minifyNdjson, minifyToml, minifyXml, ndjsonToJsonArray, parseCsv, parseEnv, parseIni, parseXmlToObject, stringifyIni, toCsvString, tomlToJson, validateEnvKey, validateIni, validateNdjson, validateToml, validateXml, validateYaml, xmlToJson };

package/dist/{data-CakDxAcT.d.cts → data-D8XTI7Du.d.cts}

@@ -10,6 +10,7 @@
  *  - csv-viewer      : detectDelimiter, parseCsv, csvToJson, toCsvString
  *  - ini-parser      : parseIni, stringifyIni, iniToJson, jsonToIni, getSection, getSectionNames, validateIni
  *  - env-parser      : parseEnv, envToJson, envToExport, validateEnvKey
+ *  - env-diff-checker: diffEnvExample
  *  - ndjson-formatter: validateNdjson, minifyNdjson, formatNdjson, ndjsonToJsonArray, jsonArrayToNdjson
  */
 interface ValidationResult {
@@ -168,6 +169,21 @@ declare function envToJson(input: string): string | {
 };
 declare function envToExport(input: string): string;
 declare function validateEnvKey(key: string): boolean;
+interface EnvDiffResult {
+    missingInExample: string[];
+    missingInEnv: string[];
+    emptyValueInExample: string[];
+    keysInBoth: number;
+}
+interface EnvDiffError {
+    error: string;
+}
+/**
+ * Diff a .env file against its .env.example template. Flags keys present in
+ * one file but not the other, plus keys that exist in both but whose
+ * .env.example value is an empty placeholder (i.e. undocumented default).
+ */
+declare function diffEnvExample(envInput: string, exampleInput: string): EnvDiffResult | EnvDiffError;
 interface NdjsonLineResult {
     line: number;
     raw: string;
@@ -196,6 +212,8 @@ declare function jsonArrayToNdjson(input: string): string | {
 };
 
 type data_CsvParseResult = CsvParseResult;
+type data_EnvDiffError = EnvDiffError;
+type data_EnvDiffResult = EnvDiffResult;
 type data_EnvEntry = EnvEntry;
 type data_EnvParseResult = EnvParseResult;
 type data_IniSection = IniSection;
@@ -209,6 +227,7 @@ type data_XmlFormatResult = XmlFormatResult;
 type data_XmlToJsonOptions = XmlToJsonOptions;
 declare const data_csvToJson: typeof csvToJson;
 declare const data_detectDelimiter: typeof detectDelimiter;
+declare const data_diffEnvExample: typeof diffEnvExample;
 declare const data_envToExport: typeof envToExport;
 declare const data_envToJson: typeof envToJson;
 declare const data_formatNdjson: typeof formatNdjson;
@@ -243,7 +262,7 @@ declare const data_validateXml: typeof validateXml;
 declare const data_validateYaml: typeof validateYaml;
 declare const data_xmlToJson: typeof xmlToJson;
 declare namespace data {
-  export { type data_CsvParseResult as CsvParseResult, type data_EnvEntry as EnvEntry, type data_EnvParseResult as EnvParseResult, type data_IniSection as IniSection, type data_NdjsonLineResult as NdjsonLineResult, type data_NdjsonValidateResult as NdjsonValidateResult, type data_ParseOptions as ParseOptions, type data_ParsedIni as ParsedIni, type data_TomlFormatResult as TomlFormatResult, type data_ValidationResult as ValidationResult, type data_XmlFormatResult as XmlFormatResult, type data_XmlToJsonOptions as XmlToJsonOptions, data_csvToJson as csvToJson, data_detectDelimiter as detectDelimiter, data_envToExport as envToExport, data_envToJson as envToJson, data_formatNdjson as formatNdjson, data_formatToml as formatToml, data_formatXml as formatXml, data_getSection as getSection, data_getSectionNames as getSectionNames, data_getTomlStats as getTomlStats, data_getXmlStats as getXmlStats, data_getYamlStats as getYamlStats, data_iniToJson as iniToJson, data_jsonArrayToNdjson as jsonArrayToNdjson, data_jsonToIni as jsonToIni, data_jsonToToml as jsonToToml, data_jsonToXml as jsonToXml, data_minifyNdjson as minifyNdjson, data_minifyToml as minifyToml, data_minifyXml as minifyXml, data_ndjsonToJsonArray as ndjsonToJsonArray, data_parseCsv as parseCsv, data_parseEnv as parseEnv, data_parseIni as parseIni, data_parseXmlToObject as parseXmlToObject, data_stringifyIni as stringifyIni, data_toCsvString as toCsvString, data_tomlToJson as tomlToJson, data_validateEnvKey as validateEnvKey, data_validateIni as validateIni, data_validateNdjson as validateNdjson, data_validateToml as validateToml, data_validateXml as validateXml, data_validateYaml as validateYaml, data_xmlToJson as xmlToJson };
+  export { type data_CsvParseResult as CsvParseResult, type data_EnvDiffError as EnvDiffError, type data_EnvDiffResult as EnvDiffResult, type data_EnvEntry as EnvEntry, type data_EnvParseResult as EnvParseResult, type data_IniSection as IniSection, type data_NdjsonLineResult as NdjsonLineResult, type data_NdjsonValidateResult as NdjsonValidateResult, type data_ParseOptions as ParseOptions, type data_ParsedIni as ParsedIni, type data_TomlFormatResult as TomlFormatResult, type data_ValidationResult as ValidationResult, type data_XmlFormatResult as XmlFormatResult, type data_XmlToJsonOptions as XmlToJsonOptions, data_csvToJson as csvToJson, data_detectDelimiter as detectDelimiter, data_diffEnvExample as diffEnvExample, data_envToExport as envToExport, data_envToJson as envToJson, data_formatNdjson as formatNdjson, data_formatToml as formatToml, data_formatXml as formatXml, data_getSection as getSection, data_getSectionNames as getSectionNames, data_getTomlStats as getTomlStats, data_getXmlStats as getXmlStats, data_getYamlStats as getYamlStats, data_iniToJson as iniToJson, data_jsonArrayToNdjson as jsonArrayToNdjson, data_jsonToIni as jsonToIni, data_jsonToToml as jsonToToml, data_jsonToXml as jsonToXml, data_minifyNdjson as minifyNdjson, data_minifyToml as minifyToml, data_minifyXml as minifyXml, data_ndjsonToJsonArray as ndjsonToJsonArray, data_parseCsv as parseCsv, data_parseEnv as parseEnv, data_parseIni as parseIni, data_parseXmlToObject as parseXmlToObject, data_stringifyIni as stringifyIni, data_toCsvString as toCsvString, data_tomlToJson as tomlToJson, data_validateEnvKey as validateEnvKey, data_validateIni as validateIni, data_validateNdjson as validateNdjson, data_validateToml as validateToml, data_validateXml as validateXml, data_validateYaml as validateYaml, data_xmlToJson as xmlToJson };
 }
 
-export { parseCsv as A, parseEnv as B, type CsvParseResult as C, parseIni as D, type EnvEntry as E, parseXmlToObject as F, stringifyIni as G, toCsvString as H, type IniSection as I, tomlToJson as J, validateEnvKey as K, validateIni as L, validateNdjson as M, type NdjsonLineResult as N, validateToml as O, type ParseOptions as P, validateXml as Q, validateYaml as R, xmlToJson as S, type TomlFormatResult as T, type ValidationResult as V, type XmlFormatResult as X, type EnvParseResult as a, type NdjsonValidateResult as b, type ParsedIni as c, data as d, type XmlToJsonOptions as e, csvToJson as f, detectDelimiter as g, envToExport as h, envToJson as i, formatNdjson as j, formatToml as k, formatXml as l, getSection as m, getSectionNames as n, getTomlStats as o, getXmlStats as p, getYamlStats as q, iniToJson as r, jsonArrayToNdjson as s, jsonToIni as t, jsonToToml as u, jsonToXml as v, minifyNdjson as w, minifyToml as x, minifyXml as y, ndjsonToJsonArray as z };
+export { minifyToml as A, minifyXml as B, type CsvParseResult as C, ndjsonToJsonArray as D, type EnvDiffError as E, parseCsv as F, parseEnv as G, parseIni as H, type IniSection as I, parseXmlToObject as J, stringifyIni as K, toCsvString as L, tomlToJson as M, type NdjsonLineResult as N, validateEnvKey as O, type ParseOptions as P, validateIni as Q, validateNdjson as R, validateToml as S, type TomlFormatResult as T, validateXml as U, type ValidationResult as V, validateYaml as W, type XmlFormatResult as X, xmlToJson as Y, type EnvDiffResult as a, type EnvEntry as b, type EnvParseResult as c, data as d, type NdjsonValidateResult as e, type ParsedIni as f, type XmlToJsonOptions as g, csvToJson as h, detectDelimiter as i, diffEnvExample as j, envToExport as k, envToJson as l, formatNdjson as m, formatToml as n, formatXml as o, getSection as p, getSectionNames as q, getTomlStats as r, getXmlStats as s, getYamlStats as t, iniToJson as u, jsonArrayToNdjson as v, jsonToIni as w, jsonToToml as x, jsonToXml as y, minifyNdjson as z };

package/dist/{data-CakDxAcT.d.ts → data-D8XTI7Du.d.ts}

@@ -10,6 +10,7 @@
  *  - csv-viewer      : detectDelimiter, parseCsv, csvToJson, toCsvString
  *  - ini-parser      : parseIni, stringifyIni, iniToJson, jsonToIni, getSection, getSectionNames, validateIni
  *  - env-parser      : parseEnv, envToJson, envToExport, validateEnvKey
+ *  - env-diff-checker: diffEnvExample
  *  - ndjson-formatter: validateNdjson, minifyNdjson, formatNdjson, ndjsonToJsonArray, jsonArrayToNdjson
  */
 interface ValidationResult {
@@ -168,6 +169,21 @@ declare function envToJson(input: string): string | {
 };
 declare function envToExport(input: string): string;
 declare function validateEnvKey(key: string): boolean;
+interface EnvDiffResult {
+    missingInExample: string[];
+    missingInEnv: string[];
+    emptyValueInExample: string[];
+    keysInBoth: number;
+}
+interface EnvDiffError {
+    error: string;
+}
+/**
+ * Diff a .env file against its .env.example template. Flags keys present in
+ * one file but not the other, plus keys that exist in both but whose
+ * .env.example value is an empty placeholder (i.e. undocumented default).
+ */
+declare function diffEnvExample(envInput: string, exampleInput: string): EnvDiffResult | EnvDiffError;
 interface NdjsonLineResult {
     line: number;
     raw: string;
@@ -196,6 +212,8 @@ declare function jsonArrayToNdjson(input: string): string | {
 };
 
 type data_CsvParseResult = CsvParseResult;
+type data_EnvDiffError = EnvDiffError;
+type data_EnvDiffResult = EnvDiffResult;
 type data_EnvEntry = EnvEntry;
 type data_EnvParseResult = EnvParseResult;
 type data_IniSection = IniSection;
@@ -209,6 +227,7 @@ type data_XmlFormatResult = XmlFormatResult;
 type data_XmlToJsonOptions = XmlToJsonOptions;
 declare const data_csvToJson: typeof csvToJson;
 declare const data_detectDelimiter: typeof detectDelimiter;
+declare const data_diffEnvExample: typeof diffEnvExample;
 declare const data_envToExport: typeof envToExport;
 declare const data_envToJson: typeof envToJson;
 declare const data_formatNdjson: typeof formatNdjson;
@@ -243,7 +262,7 @@ declare const data_validateXml: typeof validateXml;
 declare const data_validateYaml: typeof validateYaml;
 declare const data_xmlToJson: typeof xmlToJson;
 declare namespace data {
-  export { type data_CsvParseResult as CsvParseResult, type data_EnvEntry as EnvEntry, type data_EnvParseResult as EnvParseResult, type data_IniSection as IniSection, type data_NdjsonLineResult as NdjsonLineResult, type data_NdjsonValidateResult as NdjsonValidateResult, type data_ParseOptions as ParseOptions, type data_ParsedIni as ParsedIni, type data_TomlFormatResult as TomlFormatResult, type data_ValidationResult as ValidationResult, type data_XmlFormatResult as XmlFormatResult, type data_XmlToJsonOptions as XmlToJsonOptions, data_csvToJson as csvToJson, data_detectDelimiter as detectDelimiter, data_envToExport as envToExport, data_envToJson as envToJson, data_formatNdjson as formatNdjson, data_formatToml as formatToml, data_formatXml as formatXml, data_getSection as getSection, data_getSectionNames as getSectionNames, data_getTomlStats as getTomlStats, data_getXmlStats as getXmlStats, data_getYamlStats as getYamlStats, data_iniToJson as iniToJson, data_jsonArrayToNdjson as jsonArrayToNdjson, data_jsonToIni as jsonToIni, data_jsonToToml as jsonToToml, data_jsonToXml as jsonToXml, data_minifyNdjson as minifyNdjson, data_minifyToml as minifyToml, data_minifyXml as minifyXml, data_ndjsonToJsonArray as ndjsonToJsonArray, data_parseCsv as parseCsv, data_parseEnv as parseEnv, data_parseIni as parseIni, data_parseXmlToObject as parseXmlToObject, data_stringifyIni as stringifyIni, data_toCsvString as toCsvString, data_tomlToJson as tomlToJson, data_validateEnvKey as validateEnvKey, data_validateIni as validateIni, data_validateNdjson as validateNdjson, data_validateToml as validateToml, data_validateXml as validateXml, data_validateYaml as validateYaml, data_xmlToJson as xmlToJson };
+  export { type data_CsvParseResult as CsvParseResult, type data_EnvDiffError as EnvDiffError, type data_EnvDiffResult as EnvDiffResult, type data_EnvEntry as EnvEntry, type data_EnvParseResult as EnvParseResult, type data_IniSection as IniSection, type data_NdjsonLineResult as NdjsonLineResult, type data_NdjsonValidateResult as NdjsonValidateResult, type data_ParseOptions as ParseOptions, type data_ParsedIni as ParsedIni, type data_TomlFormatResult as TomlFormatResult, type data_ValidationResult as ValidationResult, type data_XmlFormatResult as XmlFormatResult, type data_XmlToJsonOptions as XmlToJsonOptions, data_csvToJson as csvToJson, data_detectDelimiter as detectDelimiter, data_diffEnvExample as diffEnvExample, data_envToExport as envToExport, data_envToJson as envToJson, data_formatNdjson as formatNdjson, data_formatToml as formatToml, data_formatXml as formatXml, data_getSection as getSection, data_getSectionNames as getSectionNames, data_getTomlStats as getTomlStats, data_getXmlStats as getXmlStats, data_getYamlStats as getYamlStats, data_iniToJson as iniToJson, data_jsonArrayToNdjson as jsonArrayToNdjson, data_jsonToIni as jsonToIni, data_jsonToToml as jsonToToml, data_jsonToXml as jsonToXml, data_minifyNdjson as minifyNdjson, data_minifyToml as minifyToml, data_minifyXml as minifyXml, data_ndjsonToJsonArray as ndjsonToJsonArray, data_parseCsv as parseCsv, data_parseEnv as parseEnv, data_parseIni as parseIni, data_parseXmlToObject as parseXmlToObject, data_stringifyIni as stringifyIni, data_toCsvString as toCsvString, data_tomlToJson as tomlToJson, data_validateEnvKey as validateEnvKey, data_validateIni as validateIni, data_validateNdjson as validateNdjson, data_validateToml as validateToml, data_validateXml as validateXml, data_validateYaml as validateYaml, data_xmlToJson as xmlToJson };
 }
 
-export { parseCsv as A, parseEnv as B, type CsvParseResult as C, parseIni as D, type EnvEntry as E, parseXmlToObject as F, stringifyIni as G, toCsvString as H, type IniSection as I, tomlToJson as J, validateEnvKey as K, validateIni as L, validateNdjson as M, type NdjsonLineResult as N, validateToml as O, type ParseOptions as P, validateXml as Q, validateYaml as R, xmlToJson as S, type TomlFormatResult as T, type ValidationResult as V, type XmlFormatResult as X, type EnvParseResult as a, type NdjsonValidateResult as b, type ParsedIni as c, data as d, type XmlToJsonOptions as e, csvToJson as f, detectDelimiter as g, envToExport as h, envToJson as i, formatNdjson as j, formatToml as k, formatXml as l, getSection as m, getSectionNames as n, getTomlStats as o, getXmlStats as p, getYamlStats as q, iniToJson as r, jsonArrayToNdjson as s, jsonToIni as t, jsonToToml as u, jsonToXml as v, minifyNdjson as w, minifyToml as x, minifyXml as y, ndjsonToJsonArray as z };
+export { minifyToml as A, minifyXml as B, type CsvParseResult as C, ndjsonToJsonArray as D, type EnvDiffError as E, parseCsv as F, parseEnv as G, parseIni as H, type IniSection as I, parseXmlToObject as J, stringifyIni as K, toCsvString as L, tomlToJson as M, type NdjsonLineResult as N, validateEnvKey as O, type ParseOptions as P, validateIni as Q, validateNdjson as R, validateToml as S, type TomlFormatResult as T, validateXml as U, type ValidationResult as V, validateYaml as W, type XmlFormatResult as X, xmlToJson as Y, type EnvDiffResult as a, type EnvEntry as b, type EnvParseResult as c, data as d, type NdjsonValidateResult as e, type ParsedIni as f, type XmlToJsonOptions as g, csvToJson as h, detectDelimiter as i, diffEnvExample as j, envToExport as k, envToJson as l, formatNdjson as m, formatToml as n, formatXml as o, getSection as p, getSectionNames as q, getTomlStats as r, getXmlStats as s, getYamlStats as t, iniToJson as u, jsonArrayToNdjson as v, jsonToIni as w, jsonToToml as x, jsonToXml as y, minifyNdjson as z };

package/dist/index.cjs

@@ -4257,6 +4257,7 @@ var data_exports = {};
 __export(data_exports, {
   csvToJson: () => csvToJson2,
   detectDelimiter: () => detectDelimiter2,
+  diffEnvExample: () => diffEnvExample,
   envToExport: () => envToExport,
   envToJson: () => envToJson,
   formatNdjson: () => formatNdjson,
@@ -5331,6 +5332,23 @@ function envToExport(input) {
 function validateEnvKey(key) {
   return /^[A-Za-z_][A-Za-z0-9_]*$/.test(key);
 }
+function diffEnvExample(envInput, exampleInput) {
+  const envParsed = parseEnv(envInput);
+  if (envParsed.errors.length > 0) {
+    return { error: `.env: ${envParsed.errors.map((e) => `Line ${e.line}: ${e.message}`).join("; ")}` };
+  }
+  const exampleParsed = parseEnv(exampleInput);
+  if (exampleParsed.errors.length > 0) {
+    return { error: `.env.example: ${exampleParsed.errors.map((e) => `Line ${e.line}: ${e.message}`).join("; ")}` };
+  }
+  const envKeys = new Set(envParsed.entries.map((e) => e.key));
+  const exampleValues = new Map(exampleParsed.entries.map((e) => [e.key, e.value]));
+  const missingInExample = [...envKeys].filter((k) => !exampleValues.has(k)).sort();
+  const missingInEnv = [...exampleValues.keys()].filter((k) => !envKeys.has(k)).sort();
+  const emptyValueInExample = [...exampleValues.entries()].filter(([k, v]) => envKeys.has(k) && v === "").map(([k]) => k).sort();
+  const keysInBoth = [...envKeys].filter((k) => exampleValues.has(k)).length;
+  return { missingInExample, missingInEnv, emptyValueInExample, keysInBoth };
+}
 function validateNdjson(input) {
   const rawLines = input.split("\n");
   const lines = [];
@@ -16997,6 +17015,7 @@ function summarizeForLlm(text, maxTokens = 200, strategy = "extractive") {
 var media_exports = {};
 __export(media_exports, {
   readExifData: () => readExifData,
+  readId3Tags: () => readId3Tags,
   readImageInfo: () => readImageInfo,
   readPdfMetadata: () => readPdfMetadata,
   readWavInfo: () => readWavInfo
@@ -17513,6 +17532,215 @@ function readWavInfo(bytes) {
     fileSize
   };
 }
+var ID3V1_GENRES = [
+  "Blues",
+  "Classic Rock",
+  "Country",
+  "Dance",
+  "Disco",
+  "Funk",
+  "Grunge",
+  "Hip-Hop",
+  "Jazz",
+  "Metal",
+  "New Age",
+  "Oldies",
+  "Other",
+  "Pop",
+  "R&B",
+  "Rap",
+  "Reggae",
+  "Rock",
+  "Techno",
+  "Industrial",
+  "Alternative",
+  "Ska",
+  "Death Metal",
+  "Pranks",
+  "Soundtrack",
+  "Euro-Techno",
+  "Ambient",
+  "Trip-Hop",
+  "Vocal",
+  "Jazz+Funk",
+  "Fusion",
+  "Trance",
+  "Classical",
+  "Instrumental",
+  "Acid",
+  "House",
+  "Game",
+  "Sound Clip",
+  "Gospel",
+  "Noise",
+  "AlternRock",
+  "Bass",
+  "Soul",
+  "Punk",
+  "Space",
+  "Meditative",
+  "Instrumental Pop",
+  "Instrumental Rock",
+  "Ethnic",
+  "Gothic",
+  "Darkwave",
+  "Techno-Industrial",
+  "Electronic",
+  "Pop-Folk",
+  "Eurodance",
+  "Dream",
+  "Southern Rock",
+  "Comedy",
+  "Cult",
+  "Gangsta",
+  "Top 40",
+  "Christian Rap",
+  "Pop/Funk",
+  "Jungle",
+  "Native American",
+  "Cabaret",
+  "New Wave",
+  "Psychedelic",
+  "Rave",
+  "Showtunes",
+  "Trailer",
+  "Lo-Fi",
+  "Tribal",
+  "Acid Punk",
+  "Acid Jazz",
+  "Polka",
+  "Retro",
+  "Musical",
+  "Rock & Roll",
+  "Hard Rock"
+];
+function readSynchsafeUInt32(bytes, offset) {
+  return (bytes[offset] & 127) << 21 | (bytes[offset + 1] & 127) << 14 | (bytes[offset + 2] & 127) << 7 | bytes[offset + 3] & 127;
+}
+function readUInt32BE(bytes, offset) {
+  return (bytes[offset] << 24 | bytes[offset + 1] << 16 | bytes[offset + 2] << 8 | bytes[offset + 3]) >>> 0;
+}
+function decodeId3Text(frameBytes) {
+  if (frameBytes.length === 0) return "";
+  const encodingByte = frameBytes[0];
+  const content = frameBytes.subarray(1);
+  let out = "";
+  if (encodingByte === 3) {
+    out = Buffer.from(content).toString("utf8");
+  } else if (encodingByte === 1 || encodingByte === 2) {
+    let little = encodingByte === 1;
+    let start = 0;
+    if (encodingByte === 1 && content.length >= 2) {
+      if (content[0] === 255 && content[1] === 254) {
+        little = true;
+        start = 2;
+      } else if (content[0] === 254 && content[1] === 255) {
+        little = false;
+        start = 2;
+      }
+    }
+    for (let i = start; i + 1 < content.length; i += 2) {
+      const code = little ? content[i] | content[i + 1] << 8 : content[i] << 8 | content[i + 1];
+      if (code === 0) break;
+      out += String.fromCharCode(code);
+    }
+  } else {
+    for (const b of content) {
+      if (b === 0) break;
+      out += String.fromCharCode(b);
+    }
+  }
+  return out.replace(/\0+$/, "").trim();
+}
+function readId3v2(bytes) {
+  if (bytes.length < 10 || bytes[0] !== 73 || bytes[1] !== 68 || bytes[2] !== 51) return null;
+  const majorVersion = bytes[3];
+  const revision = bytes[4];
+  const tagSize = readSynchsafeUInt32(bytes, 6);
+  const version2 = `ID3v2.${majorVersion}.${revision}`;
+  if (majorVersion !== 3 && majorVersion !== 4) {
+    return { version: version2, frames: {}, frameCount: 0 };
+  }
+  const frames = {};
+  let offset = 10;
+  const end = Math.min(10 + tagSize, bytes.length);
+  let frameCount = 0;
+  while (offset + 10 <= end) {
+    const frameId = String.fromCharCode(bytes[offset], bytes[offset + 1], bytes[offset + 2], bytes[offset + 3]);
+    if (frameId === "\0\0\0\0") break;
+    const frameSize = majorVersion === 4 ? readSynchsafeUInt32(bytes, offset + 4) : readUInt32BE(bytes, offset + 4);
+    const frameStart = offset + 10;
+    if (frameSize <= 0 || frameStart + frameSize > bytes.length) break;
+    const frameBytes = bytes.subarray(frameStart, frameStart + frameSize);
+    if (frameId[0] === "T" && frameId !== "TXXX") {
+      frames[frameId] = decodeId3Text(frameBytes);
+    } else if (frameId === "COMM" && frameBytes.length > 4) {
+      const rebuilt = new Uint8Array(frameBytes.length - 3);
+      rebuilt[0] = frameBytes[0];
+      rebuilt.set(frameBytes.subarray(4), 1);
+      const decoded = decodeId3Text(rebuilt);
+      const parts = decoded.split("\0");
+      frames["COMM"] = (parts[parts.length - 1] || decoded).trim();
+    }
+    frameCount++;
+    offset = frameStart + frameSize;
+  }
+  return { version: version2, frames, frameCount };
+}
+function readId3v1(bytes) {
+  if (bytes.length < 128) return null;
+  const start = bytes.length - 128;
+  if (String.fromCharCode(bytes[start], bytes[start + 1], bytes[start + 2]) !== "TAG") return null;
+  const readField = (offset, length) => {
+    let s = "";
+    for (let i = 0; i < length; i++) {
+      const b = bytes[start + offset + i];
+      if (b === 0) break;
+      s += String.fromCharCode(b);
+    }
+    return s.trim();
+  };
+  const title = readField(3, 30);
+  const artist = readField(33, 30);
+  const album = readField(63, 30);
+  const year = readField(93, 4);
+  const isV11 = bytes[start + 125] === 0 && bytes[start + 126] !== 0;
+  const comment = readField(97, isV11 ? 28 : 30);
+  const genreIndex = bytes[start + 127];
+  const genre = ID3V1_GENRES[genreIndex] ?? `Unknown (${genreIndex})`;
+  const result = { genre };
+  if (title) result.title = title;
+  if (artist) result.artist = artist;
+  if (album) result.album = album;
+  if (year) result.year = year;
+  if (comment) result.comment = comment;
+  if (isV11) result.trackNumber = String(bytes[start + 126]);
+  return result;
+}
+function readId3Tags(bytes) {
+  const v2 = readId3v2(bytes);
+  const v1 = readId3v1(bytes);
+  if (v2 && Object.keys(v2.frames).length > 0) {
+    const f = v2.frames;
+    const result = { version: v2.version, frameCount: v2.frameCount };
+    if (f["TIT2"]) result.title = f["TIT2"];
+    if (f["TPE1"]) result.artist = f["TPE1"];
+    if (f["TALB"]) result.album = f["TALB"];
+    const year = f["TYER"] || f["TDRC"];
+    if (year) result.year = year;
+    if (f["TCON"]) result.genre = f["TCON"];
+    if (f["COMM"]) result.comment = f["COMM"];
+    if (f["TRCK"]) result.trackNumber = f["TRCK"];
+    return result;
+  }
+  if (v1) {
+    return { version: v1.trackNumber !== void 0 ? "ID3v1.1" : "ID3v1", ...v1 };
+  }
+  if (v2) {
+    return { error: `Unsupported ID3 tag version: ${v2.version} (only ID3v2.3, ID3v2.4, and ID3v1/1.1 are supported)` };
+  }
+  return { error: "No ID3v1 or ID3v2.3/2.4 tags found in this file" };
+}
 
 // src/index.ts
 var version = "0.1.0";

package/dist/index.d.cts

@@ -2,7 +2,7 @@ export { j as json } from './json-BjSoIS1h.cjs';
 export { e as encoding } from './encoding-7gmq-vkV.cjs';
 export { h as hashing } from './hashing-CnetQFD_.cjs';
 export { t as text } from './text-Bbx-tZ43.cjs';
-export { d as data } from './data-CakDxAcT.cjs';
+export { d as data } from './data-D8XTI7Du.cjs';
 export { g as generators } from './generators-BGtRGpJZ.cjs';
 export { t as time } from './time-DbT8fjaF.cjs';
 export { u as units } from './units-6lwDYBvX.cjs';
@@ -13,7 +13,7 @@ export { c as color } from './color-tPwZCr9H.cjs';
 export { c as css } from './css-Cf7AMGM-.cjs';
 export { m as misc } from './misc-CA3N198T.cjs';
 export { a as ai_agent } from './ai_agent-CcpkV2DR.cjs';
-export { m as media } from './media-D66WnthC.cjs';
+export { m as media } from './media-C3ZvGyKc.cjs';
 
 declare const version = "0.1.0";
 

package/dist/index.d.ts

@@ -2,7 +2,7 @@ export { j as json } from './json-BjSoIS1h.js';
 export { e as encoding } from './encoding-7gmq-vkV.js';
 export { h as hashing } from './hashing-CnetQFD_.js';
 export { t as text } from './text-Bbx-tZ43.js';
-export { d as data } from './data-CakDxAcT.js';
+export { d as data } from './data-D8XTI7Du.js';
 export { g as generators } from './generators-BGtRGpJZ.js';
 export { t as time } from './time-DbT8fjaF.js';
 export { u as units } from './units-6lwDYBvX.js';
@@ -13,7 +13,7 @@ export { c as color } from './color-tPwZCr9H.js';
 export { c as css } from './css-Cf7AMGM-.js';
 export { m as misc } from './misc-CA3N198T.js';
 export { a as ai_agent } from './ai_agent-CcpkV2DR.js';
-export { m as media } from './media-D66WnthC.js';
+export { m as media } from './media-C3ZvGyKc.js';
 
 declare const version = "0.1.0";
 

package/dist/index.js

@@ -1,4 +1,4 @@
-export { media_exports as media } from './chunk-5CKOJXFU.js';
+export { media_exports as media } from './chunk-GUUYEIU6.js';
 export { units_exports as units } from './chunk-QJE743LY.js';
 export { network_exports as network } from './chunk-V5JKVDBA.js';
 export { api_exports as api } from './chunk-Q3B3YWOA.js';
@@ -11,7 +11,7 @@ export { json_exports as json } from './chunk-TSAGO3XP.js';
 export { encoding_exports as encoding } from './chunk-IPR7FSX4.js';
 export { hashing_exports as hashing } from './chunk-GEFVMGZR.js';
 export { text_exports as text } from './chunk-F57WMKZO.js';
-export { data_exports as data } from './chunk-DNCOIO5N.js';
+export { data_exports as data } from './chunk-TINQFTLO.js';
 export { generators_exports as generators } from './chunk-2CJSLYWI.js';
 export { time_exports as time } from './chunk-ZPQZEIXP.js';
 import './chunk-MLKGABMK.js';

package/dist/{media-D66WnthC.d.cts → media-C3ZvGyKc.d.cts}

@@ -86,9 +86,33 @@ interface WavInfoError {
  * rarer RF64 variant used for files over 4GB).
  */
 declare function readWavInfo(bytes: Uint8Array): WavInfo | WavInfoError;
+interface Id3Tags {
+    version: string;
+    title?: string;
+    artist?: string;
+    album?: string;
+    year?: string;
+    genre?: string;
+    comment?: string;
+    trackNumber?: string;
+    frameCount?: number;
+}
+interface Id3TagsError {
+    error: string;
+}
+/**
+ * Read ID3 tags (title, artist, album, year, genre, comment, track number)
+ * directly from an MP3 file's bytes, without any audio-decoding library.
+ * Prefers an ID3v2.3/2.4 header at the start of the file; falls back to a
+ * classic ID3v1/1.1 128-byte trailer if no ID3v2 text frames are found.
+ * ID3v2.2 tags are detected but their 3-character frame IDs are not decoded.
+ */
+declare function readId3Tags(bytes: Uint8Array): Id3Tags | Id3TagsError;
 
 type media_ExifData = ExifData;
 type media_ExifError = ExifError;
+type media_Id3Tags = Id3Tags;
+type media_Id3TagsError = Id3TagsError;
 type media_ImageFormat = ImageFormat;
 type media_ImageInfo = ImageInfo;
 type media_ImageInfoError = ImageInfoError;
@@ -97,11 +121,12 @@ type media_PdfMetadataError = PdfMetadataError;
 type media_WavInfo = WavInfo;
 type media_WavInfoError = WavInfoError;
 declare const media_readExifData: typeof readExifData;
+declare const media_readId3Tags: typeof readId3Tags;
 declare const media_readImageInfo: typeof readImageInfo;
 declare const media_readPdfMetadata: typeof readPdfMetadata;
 declare const media_readWavInfo: typeof readWavInfo;
 declare namespace media {
-  export { type media_ExifData as ExifData, type media_ExifError as ExifError, type media_ImageFormat as ImageFormat, type media_ImageInfo as ImageInfo, type media_ImageInfoError as ImageInfoError, type media_PdfMetadata as PdfMetadata, type media_PdfMetadataError as PdfMetadataError, type media_WavInfo as WavInfo, type media_WavInfoError as WavInfoError, media_readExifData as readExifData, media_readImageInfo as readImageInfo, media_readPdfMetadata as readPdfMetadata, media_readWavInfo as readWavInfo };
+  export { type media_ExifData as ExifData, type media_ExifError as ExifError, type media_Id3Tags as Id3Tags, type media_Id3TagsError as Id3TagsError, type media_ImageFormat as ImageFormat, type media_ImageInfo as ImageInfo, type media_ImageInfoError as ImageInfoError, type media_PdfMetadata as PdfMetadata, type media_PdfMetadataError as PdfMetadataError, type media_WavInfo as WavInfo, type media_WavInfoError as WavInfoError, media_readExifData as readExifData, media_readId3Tags as readId3Tags, media_readImageInfo as readImageInfo, media_readPdfMetadata as readPdfMetadata, media_readWavInfo as readWavInfo };
 }
 
-export { type ExifData as E, type ImageFormat as I, type PdfMetadata as P, type WavInfo as W, type ExifError as a, type ImageInfo as b, type ImageInfoError as c, type PdfMetadataError as d, type WavInfoError as e, readImageInfo as f, readPdfMetadata as g, readWavInfo as h, media as m, readExifData as r };
+export { type ExifData as E, type Id3Tags as I, type PdfMetadata as P, type WavInfo as W, type ExifError as a, type Id3TagsError as b, type ImageFormat as c, type ImageInfo as d, type ImageInfoError as e, type PdfMetadataError as f, type WavInfoError as g, readId3Tags as h, readImageInfo as i, readPdfMetadata as j, readWavInfo as k, media as m, readExifData as r };

package/dist/{media-D66WnthC.d.ts → media-C3ZvGyKc.d.ts}

@@ -86,9 +86,33 @@ interface WavInfoError {
  * rarer RF64 variant used for files over 4GB).
  */
 declare function readWavInfo(bytes: Uint8Array): WavInfo | WavInfoError;
+interface Id3Tags {
+    version: string;
+    title?: string;
+    artist?: string;
+    album?: string;
+    year?: string;
+    genre?: string;
+    comment?: string;
+    trackNumber?: string;
+    frameCount?: number;
+}
+interface Id3TagsError {
+    error: string;
+}
+/**
+ * Read ID3 tags (title, artist, album, year, genre, comment, track number)
+ * directly from an MP3 file's bytes, without any audio-decoding library.
+ * Prefers an ID3v2.3/2.4 header at the start of the file; falls back to a
+ * classic ID3v1/1.1 128-byte trailer if no ID3v2 text frames are found.
+ * ID3v2.2 tags are detected but their 3-character frame IDs are not decoded.
+ */
+declare function readId3Tags(bytes: Uint8Array): Id3Tags | Id3TagsError;
 
 type media_ExifData = ExifData;
 type media_ExifError = ExifError;
+type media_Id3Tags = Id3Tags;
+type media_Id3TagsError = Id3TagsError;
 type media_ImageFormat = ImageFormat;
 type media_ImageInfo = ImageInfo;
 type media_ImageInfoError = ImageInfoError;
@@ -97,11 +121,12 @@ type media_PdfMetadataError = PdfMetadataError;
 type media_WavInfo = WavInfo;
 type media_WavInfoError = WavInfoError;
 declare const media_readExifData: typeof readExifData;
+declare const media_readId3Tags: typeof readId3Tags;
 declare const media_readImageInfo: typeof readImageInfo;
 declare const media_readPdfMetadata: typeof readPdfMetadata;
 declare const media_readWavInfo: typeof readWavInfo;
 declare namespace media {
-  export { type media_ExifData as ExifData, type media_ExifError as ExifError, type media_ImageFormat as ImageFormat, type media_ImageInfo as ImageInfo, type media_ImageInfoError as ImageInfoError, type media_PdfMetadata as PdfMetadata, type media_PdfMetadataError as PdfMetadataError, type media_WavInfo as WavInfo, type media_WavInfoError as WavInfoError, media_readExifData as readExifData, media_readImageInfo as readImageInfo, media_readPdfMetadata as readPdfMetadata, media_readWavInfo as readWavInfo };
+  export { type media_ExifData as ExifData, type media_ExifError as ExifError, type media_Id3Tags as Id3Tags, type media_Id3TagsError as Id3TagsError, type media_ImageFormat as ImageFormat, type media_ImageInfo as ImageInfo, type media_ImageInfoError as ImageInfoError, type media_PdfMetadata as PdfMetadata, type media_PdfMetadataError as PdfMetadataError, type media_WavInfo as WavInfo, type media_WavInfoError as WavInfoError, media_readExifData as readExifData, media_readId3Tags as readId3Tags, media_readImageInfo as readImageInfo, media_readPdfMetadata as readPdfMetadata, media_readWavInfo as readWavInfo };
 }
 
-export { type ExifData as E, type ImageFormat as I, type PdfMetadata as P, type WavInfo as W, type ExifError as a, type ImageInfo as b, type ImageInfoError as c, type PdfMetadataError as d, type WavInfoError as e, readImageInfo as f, readPdfMetadata as g, readWavInfo as h, media as m, readExifData as r };
+export { type ExifData as E, type Id3Tags as I, type PdfMetadata as P, type WavInfo as W, type ExifError as a, type Id3TagsError as b, type ImageFormat as c, type ImageInfo as d, type ImageInfoError as e, type PdfMetadataError as f, type WavInfoError as g, readId3Tags as h, readImageInfo as i, readPdfMetadata as j, readWavInfo as k, media as m, readExifData as r };

package/dist/tools/data.cjs

@@ -1064,6 +1064,23 @@ function envToExport(input) {
 function validateEnvKey(key) {
   return /^[A-Za-z_][A-Za-z0-9_]*$/.test(key);
 }
+function diffEnvExample(envInput, exampleInput) {
+  const envParsed = parseEnv(envInput);
+  if (envParsed.errors.length > 0) {
+    return { error: `.env: ${envParsed.errors.map((e) => `Line ${e.line}: ${e.message}`).join("; ")}` };
+  }
+  const exampleParsed = parseEnv(exampleInput);
+  if (exampleParsed.errors.length > 0) {
+    return { error: `.env.example: ${exampleParsed.errors.map((e) => `Line ${e.line}: ${e.message}`).join("; ")}` };
+  }
+  const envKeys = new Set(envParsed.entries.map((e) => e.key));
+  const exampleValues = new Map(exampleParsed.entries.map((e) => [e.key, e.value]));
+  const missingInExample = [...envKeys].filter((k) => !exampleValues.has(k)).sort();
+  const missingInEnv = [...exampleValues.keys()].filter((k) => !envKeys.has(k)).sort();
+  const emptyValueInExample = [...exampleValues.entries()].filter(([k, v]) => envKeys.has(k) && v === "").map(([k]) => k).sort();
+  const keysInBoth = [...envKeys].filter((k) => exampleValues.has(k)).length;
+  return { missingInExample, missingInEnv, emptyValueInExample, keysInBoth };
+}
 function validateNdjson(input) {
   const rawLines = input.split("\n");
   const lines = [];
@@ -1125,6 +1142,7 @@ function jsonArrayToNdjson(input) {
 
 exports.csvToJson = csvToJson;
 exports.detectDelimiter = detectDelimiter;
+exports.diffEnvExample = diffEnvExample;
 exports.envToExport = envToExport;
 exports.envToJson = envToJson;
 exports.formatNdjson = formatNdjson;

package/dist/tools/data.d.cts

@@ -1 +1 @@
-export { C as CsvParseResult, E as EnvEntry, a as EnvParseResult, I as IniSection, N as NdjsonLineResult, b as NdjsonValidateResult, P as ParseOptions, c as ParsedIni, T as TomlFormatResult, V as ValidationResult, X as XmlFormatResult, e as XmlToJsonOptions, f as csvToJson, g as detectDelimiter, h as envToExport, i as envToJson, j as formatNdjson, k as formatToml, l as formatXml, m as getSection, n as getSectionNames, o as getTomlStats, p as getXmlStats, q as getYamlStats, r as iniToJson, s as jsonArrayToNdjson, t as jsonToIni, u as jsonToToml, v as jsonToXml, w as minifyNdjson, x as minifyToml, y as minifyXml, z as ndjsonToJsonArray, A as parseCsv, B as parseEnv, D as parseIni, F as parseXmlToObject, G as stringifyIni, H as toCsvString, J as tomlToJson, K as validateEnvKey, L as validateIni, M as validateNdjson, O as validateToml, Q as validateXml, R as validateYaml, S as xmlToJson } from '../data-CakDxAcT.cjs';
+export { C as CsvParseResult, E as EnvDiffError, a as EnvDiffResult, b as EnvEntry, c as EnvParseResult, I as IniSection, N as NdjsonLineResult, e as NdjsonValidateResult, P as ParseOptions, f as ParsedIni, T as TomlFormatResult, V as ValidationResult, X as XmlFormatResult, g as XmlToJsonOptions, h as csvToJson, i as detectDelimiter, j as diffEnvExample, k as envToExport, l as envToJson, m as formatNdjson, n as formatToml, o as formatXml, p as getSection, q as getSectionNames, r as getTomlStats, s as getXmlStats, t as getYamlStats, u as iniToJson, v as jsonArrayToNdjson, w as jsonToIni, x as jsonToToml, y as jsonToXml, z as minifyNdjson, A as minifyToml, B as minifyXml, D as ndjsonToJsonArray, F as parseCsv, G as parseEnv, H as parseIni, J as parseXmlToObject, K as stringifyIni, L as toCsvString, M as tomlToJson, O as validateEnvKey, Q as validateIni, R as validateNdjson, S as validateToml, U as validateXml, W as validateYaml, Y as xmlToJson } from '../data-D8XTI7Du.cjs';

package/dist/tools/data.d.ts

@@ -1 +1 @@
-export { C as CsvParseResult, E as EnvEntry, a as EnvParseResult, I as IniSection, N as NdjsonLineResult, b as NdjsonValidateResult, P as ParseOptions, c as ParsedIni, T as TomlFormatResult, V as ValidationResult, X as XmlFormatResult, e as XmlToJsonOptions, f as csvToJson, g as detectDelimiter, h as envToExport, i as envToJson, j as formatNdjson, k as formatToml, l as formatXml, m as getSection, n as getSectionNames, o as getTomlStats, p as getXmlStats, q as getYamlStats, r as iniToJson, s as jsonArrayToNdjson, t as jsonToIni, u as jsonToToml, v as jsonToXml, w as minifyNdjson, x as minifyToml, y as minifyXml, z as ndjsonToJsonArray, A as parseCsv, B as parseEnv, D as parseIni, F as parseXmlToObject, G as stringifyIni, H as toCsvString, J as tomlToJson, K as validateEnvKey, L as validateIni, M as validateNdjson, O as validateToml, Q as validateXml, R as validateYaml, S as xmlToJson } from '../data-CakDxAcT.js';
+export { C as CsvParseResult, E as EnvDiffError, a as EnvDiffResult, b as EnvEntry, c as EnvParseResult, I as IniSection, N as NdjsonLineResult, e as NdjsonValidateResult, P as ParseOptions, f as ParsedIni, T as TomlFormatResult, V as ValidationResult, X as XmlFormatResult, g as XmlToJsonOptions, h as csvToJson, i as detectDelimiter, j as diffEnvExample, k as envToExport, l as envToJson, m as formatNdjson, n as formatToml, o as formatXml, p as getSection, q as getSectionNames, r as getTomlStats, s as getXmlStats, t as getYamlStats, u as iniToJson, v as jsonArrayToNdjson, w as jsonToIni, x as jsonToToml, y as jsonToXml, z as minifyNdjson, A as minifyToml, B as minifyXml, D as ndjsonToJsonArray, F as parseCsv, G as parseEnv, H as parseIni, J as parseXmlToObject, K as stringifyIni, L as toCsvString, M as tomlToJson, O as validateEnvKey, Q as validateIni, R as validateNdjson, S as validateToml, U as validateXml, W as validateYaml, Y as xmlToJson } from '../data-D8XTI7Du.js';

package/dist/tools/data.js

@@ -1,2 +1,2 @@
-export { csvToJson, detectDelimiter, envToExport, envToJson, formatNdjson, formatToml, formatXml, getSection, getSectionNames, getTomlStats, getXmlStats, getYamlStats, iniToJson, jsonArrayToNdjson, jsonToIni, jsonToToml, jsonToXml, minifyNdjson, minifyToml, minifyXml, ndjsonToJsonArray, parseCsv, parseEnv, parseIni, parseXmlToObject, stringifyIni, toCsvString, tomlToJson, validateEnvKey, validateIni, validateNdjson, validateToml, validateXml, validateYaml, xmlToJson } from '../chunk-DNCOIO5N.js';
+export { csvToJson, detectDelimiter, diffEnvExample, envToExport, envToJson, formatNdjson, formatToml, formatXml, getSection, getSectionNames, getTomlStats, getXmlStats, getYamlStats, iniToJson, jsonArrayToNdjson, jsonToIni, jsonToToml, jsonToXml, minifyNdjson, minifyToml, minifyXml, ndjsonToJsonArray, parseCsv, parseEnv, parseIni, parseXmlToObject, stringifyIni, toCsvString, tomlToJson, validateEnvKey, validateIni, validateNdjson, validateToml, validateXml, validateYaml, xmlToJson } from '../chunk-TINQFTLO.js';
 import '../chunk-MLKGABMK.js';

package/dist/tools/media.cjs

@@ -513,8 +513,218 @@ function readWavInfo(bytes) {
     fileSize
   };
 }
+var ID3V1_GENRES = [
+  "Blues",
+  "Classic Rock",
+  "Country",
+  "Dance",
+  "Disco",
+  "Funk",
+  "Grunge",
+  "Hip-Hop",
+  "Jazz",
+  "Metal",
+  "New Age",
+  "Oldies",
+  "Other",
+  "Pop",
+  "R&B",
+  "Rap",
+  "Reggae",
+  "Rock",
+  "Techno",
+  "Industrial",
+  "Alternative",
+  "Ska",
+  "Death Metal",
+  "Pranks",
+  "Soundtrack",
+  "Euro-Techno",
+  "Ambient",
+  "Trip-Hop",
+  "Vocal",
+  "Jazz+Funk",
+  "Fusion",
+  "Trance",
+  "Classical",
+  "Instrumental",
+  "Acid",
+  "House",
+  "Game",
+  "Sound Clip",
+  "Gospel",
+  "Noise",
+  "AlternRock",
+  "Bass",
+  "Soul",
+  "Punk",
+  "Space",
+  "Meditative",
+  "Instrumental Pop",
+  "Instrumental Rock",
+  "Ethnic",
+  "Gothic",
+  "Darkwave",
+  "Techno-Industrial",
+  "Electronic",
+  "Pop-Folk",
+  "Eurodance",
+  "Dream",
+  "Southern Rock",
+  "Comedy",
+  "Cult",
+  "Gangsta",
+  "Top 40",
+  "Christian Rap",
+  "Pop/Funk",
+  "Jungle",
+  "Native American",
+  "Cabaret",
+  "New Wave",
+  "Psychedelic",
+  "Rave",
+  "Showtunes",
+  "Trailer",
+  "Lo-Fi",
+  "Tribal",
+  "Acid Punk",
+  "Acid Jazz",
+  "Polka",
+  "Retro",
+  "Musical",
+  "Rock & Roll",
+  "Hard Rock"
+];
+function readSynchsafeUInt32(bytes, offset) {
+  return (bytes[offset] & 127) << 21 | (bytes[offset + 1] & 127) << 14 | (bytes[offset + 2] & 127) << 7 | bytes[offset + 3] & 127;
+}
+function readUInt32BE(bytes, offset) {
+  return (bytes[offset] << 24 | bytes[offset + 1] << 16 | bytes[offset + 2] << 8 | bytes[offset + 3]) >>> 0;
+}
+function decodeId3Text(frameBytes) {
+  if (frameBytes.length === 0) return "";
+  const encodingByte = frameBytes[0];
+  const content = frameBytes.subarray(1);
+  let out = "";
+  if (encodingByte === 3) {
+    out = Buffer.from(content).toString("utf8");
+  } else if (encodingByte === 1 || encodingByte === 2) {
+    let little = encodingByte === 1;
+    let start = 0;
+    if (encodingByte === 1 && content.length >= 2) {
+      if (content[0] === 255 && content[1] === 254) {
+        little = true;
+        start = 2;
+      } else if (content[0] === 254 && content[1] === 255) {
+        little = false;
+        start = 2;
+      }
+    }
+    for (let i = start; i + 1 < content.length; i += 2) {
+      const code = little ? content[i] | content[i + 1] << 8 : content[i] << 8 | content[i + 1];
+      if (code === 0) break;
+      out += String.fromCharCode(code);
+    }
+  } else {
+    for (const b of content) {
+      if (b === 0) break;
+      out += String.fromCharCode(b);
+    }
+  }
+  return out.replace(/\0+$/, "").trim();
+}
+function readId3v2(bytes) {
+  if (bytes.length < 10 || bytes[0] !== 73 || bytes[1] !== 68 || bytes[2] !== 51) return null;
+  const majorVersion = bytes[3];
+  const revision = bytes[4];
+  const tagSize = readSynchsafeUInt32(bytes, 6);
+  const version = `ID3v2.${majorVersion}.${revision}`;
+  if (majorVersion !== 3 && majorVersion !== 4) {
+    return { version, frames: {}, frameCount: 0 };
+  }
+  const frames = {};
+  let offset = 10;
+  const end = Math.min(10 + tagSize, bytes.length);
+  let frameCount = 0;
+  while (offset + 10 <= end) {
+    const frameId = String.fromCharCode(bytes[offset], bytes[offset + 1], bytes[offset + 2], bytes[offset + 3]);
+    if (frameId === "\0\0\0\0") break;
+    const frameSize = majorVersion === 4 ? readSynchsafeUInt32(bytes, offset + 4) : readUInt32BE(bytes, offset + 4);
+    const frameStart = offset + 10;
+    if (frameSize <= 0 || frameStart + frameSize > bytes.length) break;
+    const frameBytes = bytes.subarray(frameStart, frameStart + frameSize);
+    if (frameId[0] === "T" && frameId !== "TXXX") {
+      frames[frameId] = decodeId3Text(frameBytes);
+    } else if (frameId === "COMM" && frameBytes.length > 4) {
+      const rebuilt = new Uint8Array(frameBytes.length - 3);
+      rebuilt[0] = frameBytes[0];
+      rebuilt.set(frameBytes.subarray(4), 1);
+      const decoded = decodeId3Text(rebuilt);
+      const parts = decoded.split("\0");
+      frames["COMM"] = (parts[parts.length - 1] || decoded).trim();
+    }
+    frameCount++;
+    offset = frameStart + frameSize;
+  }
+  return { version, frames, frameCount };
+}
+function readId3v1(bytes) {
+  if (bytes.length < 128) return null;
+  const start = bytes.length - 128;
+  if (String.fromCharCode(bytes[start], bytes[start + 1], bytes[start + 2]) !== "TAG") return null;
+  const readField = (offset, length) => {
+    let s = "";
+    for (let i = 0; i < length; i++) {
+      const b = bytes[start + offset + i];
+      if (b === 0) break;
+      s += String.fromCharCode(b);
+    }
+    return s.trim();
+  };
+  const title = readField(3, 30);
+  const artist = readField(33, 30);
+  const album = readField(63, 30);
+  const year = readField(93, 4);
+  const isV11 = bytes[start + 125] === 0 && bytes[start + 126] !== 0;
+  const comment = readField(97, isV11 ? 28 : 30);
+  const genreIndex = bytes[start + 127];
+  const genre = ID3V1_GENRES[genreIndex] ?? `Unknown (${genreIndex})`;
+  const result = { genre };
+  if (title) result.title = title;
+  if (artist) result.artist = artist;
+  if (album) result.album = album;
+  if (year) result.year = year;
+  if (comment) result.comment = comment;
+  if (isV11) result.trackNumber = String(bytes[start + 126]);
+  return result;
+}
+function readId3Tags(bytes) {
+  const v2 = readId3v2(bytes);
+  const v1 = readId3v1(bytes);
+  if (v2 && Object.keys(v2.frames).length > 0) {
+    const f = v2.frames;
+    const result = { version: v2.version, frameCount: v2.frameCount };
+    if (f["TIT2"]) result.title = f["TIT2"];
+    if (f["TPE1"]) result.artist = f["TPE1"];
+    if (f["TALB"]) result.album = f["TALB"];
+    const year = f["TYER"] || f["TDRC"];
+    if (year) result.year = year;
+    if (f["TCON"]) result.genre = f["TCON"];
+    if (f["COMM"]) result.comment = f["COMM"];
+    if (f["TRCK"]) result.trackNumber = f["TRCK"];
+    return result;
+  }
+  if (v1) {
+    return { version: v1.trackNumber !== void 0 ? "ID3v1.1" : "ID3v1", ...v1 };
+  }
+  if (v2) {
+    return { error: `Unsupported ID3 tag version: ${v2.version} (only ID3v2.3, ID3v2.4, and ID3v1/1.1 are supported)` };
+  }
+  return { error: "No ID3v1 or ID3v2.3/2.4 tags found in this file" };
+}
 
 exports.readExifData = readExifData;
+exports.readId3Tags = readId3Tags;
 exports.readImageInfo = readImageInfo;
 exports.readPdfMetadata = readPdfMetadata;
 exports.readWavInfo = readWavInfo;

package/dist/tools/media.d.cts

@@ -1 +1 @@
-export { E as ExifData, a as ExifError, I as ImageFormat, b as ImageInfo, c as ImageInfoError, P as PdfMetadata, d as PdfMetadataError, W as WavInfo, e as WavInfoError, r as readExifData, f as readImageInfo, g as readPdfMetadata, h as readWavInfo } from '../media-D66WnthC.cjs';
+export { E as ExifData, a as ExifError, I as Id3Tags, b as Id3TagsError, c as ImageFormat, d as ImageInfo, e as ImageInfoError, P as PdfMetadata, f as PdfMetadataError, W as WavInfo, g as WavInfoError, r as readExifData, h as readId3Tags, i as readImageInfo, j as readPdfMetadata, k as readWavInfo } from '../media-C3ZvGyKc.cjs';

package/dist/tools/media.d.ts

@@ -1 +1 @@
-export { E as ExifData, a as ExifError, I as ImageFormat, b as ImageInfo, c as ImageInfoError, P as PdfMetadata, d as PdfMetadataError, W as WavInfo, e as WavInfoError, r as readExifData, f as readImageInfo, g as readPdfMetadata, h as readWavInfo } from '../media-D66WnthC.js';
+export { E as ExifData, a as ExifError, I as Id3Tags, b as Id3TagsError, c as ImageFormat, d as ImageInfo, e as ImageInfoError, P as PdfMetadata, f as PdfMetadataError, W as WavInfo, g as WavInfoError, r as readExifData, h as readId3Tags, i as readImageInfo, j as readPdfMetadata, k as readWavInfo } from '../media-C3ZvGyKc.js';

package/dist/tools/media.js

@@ -1,2 +1,2 @@
-export { readExifData, readImageInfo, readPdfMetadata, readWavInfo } from '../chunk-5CKOJXFU.js';
+export { readExifData, readId3Tags, readImageInfo, readPdfMetadata, readWavInfo } from '../chunk-GUUYEIU6.js';
 import '../chunk-MLKGABMK.js';

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@utilix-tech/sdk",
-  "version": "0.7.0",
-  "description": "140+ developer utility tools for Node.js: JSON, encoding, hashing, color, CSS, network and more. Runs locally, no API key required.",
+  "version": "0.8.0",
+  "description": "153+ developer utility tools for Node.js: JSON, encoding, hashing, color, CSS, network and more. Runs locally, no API key required.",
   "author": "Utilix <hello@utilix.tech>",
   "license": "MIT",
   "homepage": "https://www.utilix.tech/docs#node-sdk",
@@ -28,7 +28,12 @@
     "regex",
     "uuid",
     "api-client",
-    "utilix"
+    "utilix",
+    "ai-agent",
+    "llm-tools",
+    "rag",
+    "yaml",
+    "base64"
   ],
   "engines": {
     "node": ">=18"