bytecut 0.0.0-stage → 0.0.1

package/dist/cli.js

@@ -0,0 +1,138 @@
+#!/usr/bin/env node
+import {
+  collectDoctorReport,
+  formatDoctorReport
+} from "./chunk-326CQQWX.js";
+import {
+  svgoEngine
+} from "./chunk-LTWUPQDT.js";
+import {
+  audit
+} from "./chunk-N536JFSF.js";
+import {
+  package_default
+} from "./chunk-G53LNJ5O.js";
+import {
+  formatAuditReport
+} from "./chunk-CEZK3RQJ.js";
+import "./chunk-3DBJKHOD.js";
+import "./chunk-5R7LR5BB.js";
+import {
+  sharpImageEngine
+} from "./chunk-XFJ3HW4X.js";
+import "./chunk-NAKV7HS5.js";
+import {
+  createVideoEngine,
+  discover,
+  ffmpegInstallText,
+  ffmpegStatus,
+  makeScorerFactory,
+  noAssetsMessage
+} from "./chunk-4XOB3C34.js";
+import {
+  doctorDeps
+} from "./chunk-M6ZDSATP.js";
+import "./chunk-WE7AEDVI.js";
+import "./chunk-YBEC5QGV.js";
+import "./chunk-LHTI3JMC.js";
+import {
+  guarded
+} from "./chunk-J2XJO4JZ.js";
+import "./chunk-TWI2OZJZ.js";
+
+// src/cli/index.ts
+import { defineCommand, runMain } from "citty";
+
+// src/cli/interactive.ts
+function isInteractive(env = process.env, stdin = process.stdin, stdout = process.stdout) {
+  const ci = env.CI;
+  const inCi = ci !== void 0 && ci !== "" && ci !== "0" && ci.toLowerCase() !== "false";
+  return Boolean(stdin.isTTY && stdout.isTTY) && !inCi;
+}
+async function runDefault() {
+  const found = await discover([]);
+  if (found.scanInputs.length === 0) {
+    console.error(noAssetsMessage("", found.project));
+    process.exitCode = 2;
+    return;
+  }
+  if (isInteractive()) {
+    const { runTui } = await import("./tui-J4Y44IL7.js");
+    await runTui({
+      projectRoot: found.projectRoot,
+      project: found.project,
+      config: found.config,
+      inputs: found.scanInputs,
+      outDir: found.outDir,
+      engine: sharpImageEngine,
+      svgEngine: svgoEngine,
+      toolVersion: package_default.version,
+      ffmpeg: ffmpegStatus(found.config),
+      videoEngine: createVideoEngine({}, found.config),
+      makeScorer: makeScorerFactory(void 0, found.config),
+      needsFfmpeg: ffmpegInstallText(),
+      loadDoctor: async () => formatDoctorReport(await collectDoctorReport(doctorDeps()))
+    });
+    return;
+  }
+  const report = await audit({
+    projectRoot: found.projectRoot,
+    engine: sharpImageEngine,
+    svgEngine: svgoEngine,
+    inputs: found.scanInputs,
+    outDir: found.outDir,
+    staticRoot: found.project.staticRoot,
+    ffmpeg: ffmpegStatus(found.config),
+    videoEngine: createVideoEngine({}, found.config),
+    needsFfmpeg: ffmpegInstallText(),
+    policy: found.config.policy,
+    exclude: found.config.exclude,
+    ignore: found.config.auditIgnore,
+    settings: found.config.rules,
+    budgets: found.config.budgets,
+    // A bare `npx bytecut` in CI should not create folders in the repo.
+    persistCache: false
+  });
+  console.log(formatAuditReport(report));
+  console.log(
+    "\nNot an interactive terminal. Run `bytecut optimize -y` to write the optimized files."
+  );
+}
+
+// src/cli/index.ts
+var SUBCOMMANDS = [
+  "audit",
+  "optimize",
+  "snippet",
+  "compare",
+  "explain",
+  "init",
+  "check",
+  "doctor"
+];
+var main = defineCommand({
+  meta: {
+    name: "bytecut",
+    version: package_default.version,
+    description: "Audit and optimize images and videos in web projects"
+  },
+  // Plain `bytecut` (no subcommand): interactive UI on a TTY, audit report otherwise.
+  // citty also invokes the parent's `run` after a subcommand finishes, so bail out then, or
+  // every subcommand would be followed by a second, unrelated audit of the project.
+  run: guarded(async ({ rawArgs }) => {
+    const first = rawArgs.find((arg) => !arg.startsWith("-"));
+    if (first !== void 0 && SUBCOMMANDS.includes(first)) return;
+    await runDefault();
+  }),
+  subCommands: {
+    audit: () => import("./audit-HVW4EOLP.js").then((m) => m.default),
+    optimize: () => import("./optimize-UXM6JEDA.js").then((m) => m.default),
+    snippet: () => import("./snippet-2WVGMCNV.js").then((m) => m.default),
+    compare: () => import("./compare-6PCE6533.js").then((m) => m.default),
+    explain: () => import("./explain-SGN5BOR7.js").then((m) => m.default),
+    init: () => import("./init-WHWUANOB.js").then((m) => m.default),
+    check: () => import("./check-YONIQTM7.js").then((m) => m.default),
+    doctor: () => import("./doctor-R226JU6P.js").then((m) => m.default)
+  }
+});
+await runMain(main);

package/dist/compare-6PCE6533.js

@@ -0,0 +1,84 @@
+#!/usr/bin/env node
+import {
+  startCompareServer
+} from "./chunk-7IECTPJB.js";
+import {
+  MANIFEST_FILE,
+  parseManifest
+} from "./chunk-5R7LR5BB.js";
+import {
+  configArg,
+  discover
+} from "./chunk-4XOB3C34.js";
+import "./chunk-M6ZDSATP.js";
+import {
+  toPosix
+} from "./chunk-WE7AEDVI.js";
+import "./chunk-YBEC5QGV.js";
+import {
+  guarded
+} from "./chunk-J2XJO4JZ.js";
+import {
+  BytecutError
+} from "./chunk-TWI2OZJZ.js";
+
+// src/cli/commands/compare.ts
+import { readFile } from "fs/promises";
+import { relative, resolve } from "path";
+import { defineCommand } from "citty";
+var compare_default = defineCommand({
+  meta: {
+    name: "compare",
+    description: "Serve a before/after page for one optimized file on localhost (127.0.0.1, random port)"
+  },
+  args: {
+    ...configArg,
+    port: { type: "string", description: "Port to listen on (default: a free one)" },
+    "out-dir": { type: "string", description: "Output folder (default: from the framework)" }
+  },
+  run: guarded(async ({ args }) => {
+    const inputs = args._.map(String);
+    if (inputs.length !== 1) {
+      throw new BytecutError(
+        "BAD_ARGUMENTS",
+        "Name one optimized file, e.g. `bytecut compare public/img/hero.jpg`."
+      );
+    }
+    let port = 0;
+    if (args.port !== void 0) {
+      port = Number(args.port);
+      if (!Number.isInteger(port) || port < 0 || port > 65535) {
+        throw new BytecutError("BAD_ARGUMENTS", `--port must be 0-65535, not "${args.port}".`);
+      }
+    }
+    const found = await discover([], args["out-dir"], args.config);
+    let text;
+    try {
+      text = await readFile(resolve(found.projectRoot, found.outDir, MANIFEST_FILE), "utf8");
+    } catch {
+      throw new BytecutError(
+        "INPUT_NOT_FOUND",
+        `No manifest at ${found.outDir}/${MANIFEST_FILE}. Run \`bytecut optimize -y\` first.`
+      );
+    }
+    const source = toPosix(relative(found.projectRoot, resolve(found.projectRoot, inputs[0])));
+    const server = await startCompareServer({
+      projectRoot: found.projectRoot,
+      outDir: found.outDir,
+      manifest: parseManifest(text),
+      source,
+      port
+    });
+    console.log(`Comparing ${source}`);
+    console.log(`  ${server.url}`);
+    console.log("Local only (127.0.0.1). Press Ctrl-C to stop.");
+    await new Promise((done) => {
+      process.once("SIGINT", () => done());
+      process.once("SIGTERM", () => done());
+    });
+    await server.close();
+  })
+});
+export {
+  compare_default as default
+};

package/dist/doctor-R226JU6P.js

@@ -0,0 +1,77 @@
+#!/usr/bin/env node
+import {
+  collectDoctorReport,
+  formatDoctorReport
+} from "./chunk-326CQQWX.js";
+import {
+  doctorDeps
+} from "./chunk-M6ZDSATP.js";
+import {
+  resolveConfig
+} from "./chunk-YBEC5QGV.js";
+import {
+  isGitIgnored
+} from "./chunk-DJ45NQZD.js";
+import {
+  guarded
+} from "./chunk-J2XJO4JZ.js";
+import {
+  BytecutError,
+  detectProject,
+  loadConfig
+} from "./chunk-TWI2OZJZ.js";
+
+// src/cli/commands/doctor.ts
+import { defineCommand } from "citty";
+import { resolve } from "path";
+var doctor_default = defineCommand({
+  meta: {
+    name: "doctor",
+    description: "Check Node, sharp and ffmpeg, and report what is degraded"
+  },
+  args: {
+    config: {
+      type: "string",
+      description: "Path to a config file (default: bytecut.config.* in the project)"
+    },
+    ffmpeg: { type: "string", description: "Path to the ffmpeg binary" },
+    ffprobe: { type: "string", description: "Path to the ffprobe binary" },
+    ssimulacra2: {
+      type: "string",
+      description: "Path to a native ssimulacra2 (optional; a WebAssembly scorer is built in)"
+    },
+    json: { type: "boolean", description: "Print the report as JSON" }
+  },
+  run: guarded(async ({ args }) => {
+    const projectRoot = process.cwd();
+    let configError;
+    let resolved = await resolveConfig(projectRoot, null);
+    try {
+      resolved = await resolveConfig(projectRoot, await loadConfig(projectRoot, args.config));
+    } catch (error) {
+      if (!(error instanceof BytecutError)) throw error;
+      configError = error.message;
+      resolved = { ...resolved, project: await detectProject(projectRoot) };
+    }
+    const report = await collectDoctorReport(doctorDeps(), {
+      ffmpegFlag: args.ffmpeg,
+      ffprobeFlag: args.ffprobe,
+      ffmpegConfig: resolved.ffmpegPath,
+      ffprobeConfig: resolved.ffprobePath,
+      ssimulacra2Flag: args.ssimulacra2,
+      ssimulacra2Config: resolved.ssimulacra2Path
+    });
+    report.project = {
+      framework: resolved.project.framework,
+      configFile: resolved.loaded?.name ?? null,
+      ...configError ? { configError } : {},
+      outDir: resolved.project.outDir,
+      outDirIgnored: await isGitIgnored(projectRoot, resolve(projectRoot, resolved.project.outDir))
+    };
+    console.log(args.json ? JSON.stringify(report, null, 2) : formatDoctorReport(report));
+    if (!report.ok) process.exitCode = 1;
+  })
+});
+export {
+  doctor_default as default
+};

package/dist/explain-SGN5BOR7.js

@@ -0,0 +1,265 @@
+#!/usr/bin/env node
+import {
+  sharpImageEngine
+} from "./chunk-XFJ3HW4X.js";
+import {
+  classify,
+  classifyVideo,
+  mirroredDir,
+  plannedVideoOutputs,
+  targetWidths
+} from "./chunk-NAKV7HS5.js";
+import {
+  configArg,
+  createVideoEngine,
+  discover
+} from "./chunk-4XOB3C34.js";
+import "./chunk-M6ZDSATP.js";
+import {
+  toPosix
+} from "./chunk-WE7AEDVI.js";
+import {
+  getVideoPreset
+} from "./chunk-YBEC5QGV.js";
+import {
+  guarded
+} from "./chunk-J2XJO4JZ.js";
+import {
+  BytecutError,
+  formatBytes,
+  matchesGlob
+} from "./chunk-TWI2OZJZ.js";
+
+// src/cli/commands/explain.ts
+import { stat } from "fs/promises";
+import { resolve as resolve2 } from "path";
+import { defineCommand } from "citty";
+
+// src/core/config/explain.ts
+import { readFile } from "fs/promises";
+import { extname, posix, relative, resolve } from "path";
+var RASTER = /* @__PURE__ */ new Set([".jpg", ".jpeg", ".png", ".webp", ".avif", ".gif"]);
+var VIDEO = /* @__PURE__ */ new Set([".mp4", ".webm", ".mov", ".m4v", ".mkv"]);
+async function explainFile(options) {
+  const { config, projectRoot } = options;
+  const absolute = resolve(projectRoot, options.file);
+  const source = toPosix(relative(projectRoot, absolute));
+  const ext = extname(source).toLowerCase();
+  const { catalog } = config;
+  const base = {
+    source,
+    outDir: config.project.outDir,
+    publicPath: config.project.publicPath,
+    excluded: false,
+    auditIgnored: config.auditIgnore.some((p) => matchesGlob(p, source))
+  };
+  const none = (kind, reason) => ({
+    ...base,
+    kind,
+    decision: { by: "unavailable", reason },
+    preset: null,
+    chain: [],
+    changedBy: [],
+    resolved: null,
+    outputs: []
+  });
+  if (ext === ".svg") return none("svg", "SVG output is not implemented yet");
+  const isVideo = VIDEO.has(ext);
+  if (!isVideo && !RASTER.has(ext))
+    return none("unsupported", `${ext || "this"} is not a supported type`);
+  const matched = config.policy.assetFor(source);
+  const detail = (preset2) => ({
+    chain: catalog.origin[preset2]?.chain ?? [preset2],
+    changedBy: catalog.origin[preset2]?.overrides ?? []
+  });
+  const pick = (kind, classifier) => {
+    const known = (name) => kind === "image" ? catalog.image[name] : catalog.video[name];
+    if (options.presetFlag) {
+      if (!known(options.presetFlag)) {
+        return {
+          preset: null,
+          decision: {
+            by: "unavailable",
+            reason: `--preset ${options.presetFlag} is not a ${kind} preset`
+          }
+        };
+      }
+      return {
+        preset: options.presetFlag,
+        decision: { by: "flag", reason: `forced with --preset ${options.presetFlag}` }
+      };
+    }
+    if (matched && known(matched.preset)) {
+      return {
+        preset: matched.preset,
+        decision: {
+          by: "assets",
+          pattern: matched.pattern,
+          reason: `matched assets "${matched.pattern}"`
+        }
+      };
+    }
+    const verdict = classifier();
+    if (!verdict) {
+      return {
+        preset: null,
+        decision: {
+          by: "unavailable",
+          reason: "classifying a video needs ffprobe, which was not found"
+        }
+      };
+    }
+    return {
+      preset: verdict.preset,
+      decision: { by: "classifier", reason: verdict.reason, confidence: verdict.confidence }
+    };
+  };
+  if (!isVideo) {
+    const data = await readFile(absolute);
+    const analysis = await options.engine.analyze(data);
+    if (!(analysis.animated && analysis.format === "gif")) {
+      const { preset: preset2, decision: decision2 } = pick("image", () => classify(source, analysis));
+      const resolved2 = preset2 ? catalog.image[preset2] : null;
+      const dir = mirroredDir(source, config.project.staticRoot);
+      const name = posix.basename(source, posix.extname(source));
+      const outputs = resolved2 ? targetWidths(resolved2.widths, analysis.width).flatMap(
+        (w) => resolved2.formats.map((f) => posix.join(dir, name, `${name}-${w}.${f}`))
+      ) : [];
+      return {
+        ...base,
+        kind: "image",
+        decision: decision2,
+        preset: preset2,
+        ...preset2 ? detail(preset2) : { chain: [], changedBy: [] },
+        resolved: resolved2,
+        outputs
+      };
+    }
+  }
+  const probe = options.videoEngine ? await options.videoEngine.probe(absolute).catch(() => null) : null;
+  const isGif = ext === ".gif";
+  const { preset, decision } = pick("video", () => {
+    if (isGif) return { preset: "gif-to-video", reason: "animated GIF", confidence: "high" };
+    return probe ? classifyVideo(source, probe) : null;
+  });
+  const resolved = preset ? getVideoPreset(preset, catalog) ?? null : null;
+  return {
+    ...base,
+    kind: "video",
+    decision,
+    preset,
+    ...preset ? detail(preset) : { chain: [], changedBy: [] },
+    resolved,
+    outputs: resolved && probe ? plannedVideoOutputs(source, config.project.staticRoot, resolved, probe).map((o) => o.path) : []
+  };
+}
+function formatExplanation(e) {
+  const lines = [e.source];
+  lines.push(`  type:     ${e.kind}`);
+  if (e.preset === null) {
+    lines.push(`  preset:   none (${e.decision.reason})`);
+  } else {
+    const how = e.decision.by === "assets" ? `assets rule "${e.decision.pattern}"` : e.decision.by === "flag" ? "the --preset flag" : e.decision.by === "classifier" ? `classifier, ${e.decision.confidence} confidence: ${e.decision.reason}` : e.decision.reason;
+    lines.push(`  preset:   ${e.preset}  (from ${how})`);
+    if (e.chain.length > 1 || e.changedBy.length > 0) {
+      lines.push(`  extends:  ${e.chain.join(" \u2192 ")}`);
+      if (e.changedBy.length > 0) lines.push(`  changed:  ${e.changedBy.join(", ")}`);
+    }
+  }
+  const r = e.resolved;
+  if (r && "widths" in r) {
+    lines.push(`  widths:   ${r.widths.join(", ")} (never above the source)`);
+    lines.push(`  formats:  ${r.formats.join(", ")}`);
+    for (const f of r.formats) {
+      const lossless = r.lossless ? ", lossless" : "";
+      lines.push(
+        `  ${f}:     quality ${r.encoders[f].quality}, effort ${r.encoders[f].effort}${lossless}`
+      );
+    }
+    lines.push(`  priority: ${r.priority ? "yes (fetchpriority=high, never lazy)" : "no"}`);
+    if (r.search) {
+      const parts = [`ssimulacra2 >= ${r.search.target}`];
+      if (r.search.maxBytes !== void 0) {
+        parts.push(
+          `at most ${formatBytes(r.search.maxBytes)} per file, quality may fall to a score of ${r.search.floor}`
+        );
+      }
+      lines.push(
+        `  search:   ${parts.join("; ")} (quality is found per image; lossless outputs are exact)`
+      );
+    }
+  } else if (r) {
+    lines.push(`  codecs:   ${r.codecs.join(", ")}`);
+    lines.push(`  audio:    ${r.audio === "strip" ? "removed" : "kept"}`);
+    lines.push(
+      `  cap:      ${r.maxWidth ? `${r.maxWidth}px wide` : "no width cap"}, ${r.maxFps ? `${r.maxFps} fps` : "no fps cap"}`
+    );
+    lines.push(`  crf:      av1 ${r.crf.av1}, h264 ${r.crf.h264}`);
+    if (r.search) {
+      lines.push(
+        `  search:   ${r.search.metric} >= ${r.search.target} on the worst of 3 sampled clips (crf above is the starting point)`
+      );
+    }
+  }
+  if (e.outputs.length > 0) {
+    lines.push(`  outputs:  ${e.outDir}/`);
+    for (const o of e.outputs) lines.push(`    ${o}`);
+  }
+  if (e.auditIgnored)
+    lines.push("  note:     matched audit.ignore, so audit raises no findings for it");
+  return lines.join("\n");
+}
+
+// src/cli/commands/explain.ts
+var explain_default = defineCommand({
+  meta: {
+    name: "explain",
+    description: "Show which rule chose a file's preset and what that preset resolves to"
+  },
+  args: {
+    ...configArg,
+    preset: { type: "string", description: "Show the result of forcing this preset" },
+    json: { type: "boolean", description: "Print the explanation as JSON" },
+    ffmpeg: { type: "string", description: "Path to the ffmpeg binary" },
+    ffprobe: { type: "string", description: "Path to the ffprobe binary" }
+  },
+  run: guarded(async ({ args }) => {
+    const files = args._.map(String);
+    if (files.length === 0) {
+      throw new BytecutError(
+        "BAD_ARGUMENTS",
+        "Name a file, e.g. `bytecut explain public/img/hero.jpg`."
+      );
+    }
+    const found = await discover([], void 0, args.config);
+    const engine = createVideoEngine({ ffmpeg: args.ffmpeg, ffprobe: args.ffprobe }, found.config);
+    const results = [];
+    for (const file of files) {
+      if (!(await stat(resolve2(found.projectRoot, file)).catch(() => null))?.isFile()) {
+        throw new BytecutError("INPUT_NOT_FOUND", `No such file: ${file}`);
+      }
+      results.push(
+        await explainFile({
+          projectRoot: found.projectRoot,
+          file,
+          config: found.config,
+          engine: sharpImageEngine,
+          videoEngine: engine,
+          presetFlag: args.preset
+        })
+      );
+    }
+    if (args.json) {
+      process.stdout.write(`${JSON.stringify({ version: 1, files: results }, null, 2)}
+`);
+      return;
+    }
+    const where = found.config.loaded ? found.config.loaded.name : "no config (zero-config)";
+    console.log(`Config: ${where}
+`);
+    console.log(results.map(formatExplanation).join("\n\n"));
+  })
+});
+export {
+  explain_default as default
+};

package/dist/init-WHWUANOB.js

@@ -0,0 +1,92 @@
+#!/usr/bin/env node
+import {
+  isGitIgnored
+} from "./chunk-DJ45NQZD.js";
+import {
+  applyChoices,
+  isEmpty,
+  renderConfig
+} from "./chunk-GMHOU4Y5.js";
+import {
+  writeConfigFile
+} from "./chunk-LHTI3JMC.js";
+import {
+  guarded
+} from "./chunk-J2XJO4JZ.js";
+import {
+  BytecutError,
+  FRAMEWORKS,
+  PLACEHOLDERS,
+  detectProject,
+  findConfigFiles
+} from "./chunk-TWI2OZJZ.js";
+
+// src/cli/commands/init.ts
+import { relative } from "path";
+import { defineCommand } from "citty";
+import { resolve } from "path";
+var FILE = "bytecut.config.json";
+var init_default = defineCommand({
+  meta: {
+    name: "init",
+    description: "Write a minimal bytecut.config.json containing only non-default choices"
+  },
+  args: {
+    "out-dir": { type: "string", description: "Output folder to record" },
+    "public-path": { type: "string", description: "URL prefix to record" },
+    framework: { type: "string", description: `Framework to record (${FRAMEWORKS.join(", ")})` },
+    placeholder: {
+      type: "string",
+      description: `Placeholder to record (${PLACEHOLDERS.join(", ")})`
+    }
+  },
+  run: guarded(async ({ args }) => {
+    const projectRoot = process.cwd();
+    const existing = await findConfigFiles(projectRoot);
+    if (existing.length > 0) {
+      throw new BytecutError(
+        "CONFIG_EXISTS",
+        `${existing[0]} already exists; edit it instead. init never overwrites a config.`
+      );
+    }
+    const framework = args.framework;
+    if (framework !== void 0 && !FRAMEWORKS.includes(framework)) {
+      throw new BytecutError(
+        "BAD_ARGUMENTS",
+        `--framework must be one of ${FRAMEWORKS.join(", ")}.`
+      );
+    }
+    const placeholder = args.placeholder;
+    if (placeholder !== void 0 && !PLACEHOLDERS.includes(placeholder)) {
+      throw new BytecutError(
+        "BAD_ARGUMENTS",
+        `--placeholder must be one of ${PLACEHOLDERS.join(", ")}.`
+      );
+    }
+    const detected = await detectProject(projectRoot);
+    const effective = await detectProject(projectRoot, { framework });
+    const choices = {
+      ...args["out-dir"] && args["out-dir"] !== effective.outDir ? { outDir: args["out-dir"] } : {},
+      ...args["public-path"] && args["public-path"] !== effective.publicPath ? { publicPath: args["public-path"] } : {},
+      ...placeholder && placeholder !== "dominant-color" ? { placeholder } : {}
+    };
+    const data = applyChoices(
+      framework && framework !== detected.framework ? { framework } : {},
+      choices
+    );
+    const path = await writeConfigFile(projectRoot, FILE, renderConfig("json", data));
+    console.log(
+      isEmpty(choices) && !data.framework ? `Wrote ${relative(projectRoot, path)} with no overrides: everything is at its default.` : `Wrote ${relative(projectRoot, path)}:
+${renderConfig("json", data)}`
+    );
+    const outDir = args["out-dir"] ?? effective.outDir;
+    if (await isGitIgnored(projectRoot, resolve(projectRoot, outDir))) {
+      console.warn(
+        `Note: ${outDir} is matched by a .gitignore. bytecut's outputs are meant to be committed so deploys need no encoding step. Nothing was changed.`
+      );
+    }
+  })
+});
+export {
+  init_default as default
+};