@joycostudio/iris 0.0.0-stage → 0.0.1

package/dist/cli.js

@@ -0,0 +1,658 @@
+#!/usr/bin/env node
+
+// packages/cli/index.ts
+import { access, writeFile as writeFile2 } from "fs/promises";
+import path4 from "path";
+import { createJiti } from "jiti";
+
+// packages/node/generate.ts
+import { mkdir, readFile as readFile3, realpath as realpath2, rename, writeFile } from "fs/promises";
+import path3 from "path";
+import sharp2 from "sharp";
+
+// packages/node/discover.ts
+import { readFile } from "fs/promises";
+import path from "path";
+import { parse } from "@babel/parser";
+import fg from "fast-glob";
+import { minimatch } from "minimatch";
+var ignored = [
+  "**/node_modules/**",
+  "**/.next/**",
+  "**/.git/**",
+  "**/dist/**",
+  "**/coverage/**",
+  "**/generated/**",
+  "**/*.generated.*"
+];
+var codeFile = /\.(?:[cm]?[jt]s|[jt]sx)$/i;
+var imageFile = /\.(?:png|jpe?g|webp|avif|gif)$/i;
+async function discoverIrisSources(options, rootDir) {
+  const publicDir = path.resolve(rootDir, options.publicDir ?? "public");
+  const exclude = options.exclude ?? [];
+  const outputDir = path.resolve(rootDir, options.output);
+  const explicit = [];
+  const patterns = [];
+  const found = /* @__PURE__ */ new Set();
+  for (const source of options.sources ?? []) {
+    if (typeof source === "string" && !/^(?:https?:\/\/|\/)/i.test(source) && fg.isDynamicPattern(source))
+      patterns.push(source);
+    else explicit.push(source);
+  }
+  const globOptions = {
+    cwd: rootDir,
+    onlyFiles: true,
+    followSymbolicLinks: false,
+    ignore: [...ignored, ...exclude]
+  };
+  for (const file of await fg(patterns, globOptions)) {
+    if (!imageFile.test(file)) continue;
+    const relative = path.relative(publicDir, path.resolve(rootDir, file));
+    if (relative === ".." || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) {
+      throw new Error(
+        `Iris source pattern matched ${file} outside publicDir. Image globs must stay inside ${publicDir}.`
+      );
+    }
+    found.add(`/${relative.split(path.sep).map(encodeURIComponent).join("/")}`);
+  }
+  for (const file of (await fg(options.scan ?? [], globOptions)).sort()) {
+    if (!codeFile.test(file) || /\.d\.[cm]?ts$/i.test(file) || path.resolve(rootDir, file).startsWith(outputDir + path.sep))
+      continue;
+    const code = await readFile(path.resolve(rootDir, file), "utf8");
+    try {
+      for (const source of scanImageLiterals(code, file)) found.add(source);
+    } catch (error) {
+      throw new Error(
+        `Iris could not scan ${file}: ${error instanceof Error ? error.message : String(error)}`
+      );
+    }
+  }
+  const explicitUrls = new Set(
+    explicit.map((source) => typeof source === "string" ? source : source.src)
+  );
+  const excluded = (src) => exclude.some(
+    (pattern) => src === pattern || minimatch(src, pattern, { dot: true, nonegate: true, nocomment: true })
+  );
+  return [
+    ...[...found].sort().filter((src) => !explicitUrls.has(src) && !excluded(src)),
+    ...explicit.filter(
+      (source) => !excluded(typeof source === "string" ? source : source.src)
+    )
+  ];
+}
+function scanImageLiterals(code, filename) {
+  const ast = parse(code, {
+    sourceType: "unambiguous",
+    sourceFilename: filename,
+    attachComment: false,
+    plugins: [
+      .../\.[cm]?tsx?$/i.test(filename) ? ["typescript"] : [],
+      .../\.[jt]sx$|\.[cm]?js$/i.test(filename) ? ["jsx"] : []
+    ]
+  });
+  const literals = [];
+  function walk(value) {
+    if (!value || typeof value !== "object") return;
+    if (Array.isArray(value)) {
+      value.forEach(walk);
+      return;
+    }
+    const node = value;
+    if (typeof node.type !== "string") return;
+    if (node.type.startsWith("Comment") || node.type === "BinaryExpression" || node.type === "TaggedTemplateExpression" || node.type === "ImportDeclaration" || node.type === "ExportAllDeclaration" || node.type === "TSLiteralType")
+      return;
+    if (node.type === "StringLiteral") {
+      if (typeof node.value === "string") literals.push(node.value);
+      return;
+    }
+    if (node.type === "TemplateLiteral") {
+      const template = node;
+      if (template.expressions.length === 0 && template.quasis[0]?.value.cooked)
+        literals.push(template.quasis[0].value.cooked);
+      return;
+    }
+    for (const [key, child] of Object.entries(node)) {
+      if (![
+        "comments",
+        "leadingComments",
+        "trailingComments",
+        "innerComments",
+        "loc",
+        "extra"
+      ].includes(key))
+        walk(child);
+    }
+  }
+  walk(ast.program);
+  return [
+    ...new Set(
+      literals.filter(
+        (value) => /^(?:https?:\/\/|\/).+\.(?:png|jpe?g|webp|avif|gif)(?:[?#].*)?$/i.test(
+          value
+        )
+      )
+    )
+  ].sort();
+}
+
+// packages/node/prepare.ts
+import { readFile as readFile2, realpath } from "fs/promises";
+import path2 from "path";
+import fg2 from "fast-glob";
+import sharp from "sharp";
+
+// packages/core/policy.ts
+import { minimatch as minimatch2 } from "minimatch";
+function irisFailure(code, message) {
+  return { ok: false, error: { code, message } };
+}
+function positive(value) {
+  return Number.isFinite(value) && value > 0;
+}
+function validVariant(value) {
+  return value && typeof value.url === "string" && !!value.url && positive(value.width) && positive(value.height) && Number.isFinite(value.bytes) && value.bytes >= 0;
+}
+
+// packages/node/prepare.ts
+async function prepareIrisAssets({
+  iris,
+  rootDir = process.cwd(),
+  publicDir = "public",
+  fetch: fetcher = fetch
+}) {
+  const publicRoot = path2.resolve(rootDir, publicDir);
+  try {
+    let inspect2 = function(src) {
+      let pending = inspected.get(src);
+      if (!pending) {
+        pending = (async () => {
+          let bytes;
+          if (/^https?:\/\//i.test(src)) {
+            const response = await fetcher(src, {
+              signal: AbortSignal.timeout(3e4)
+            });
+            if (!response.ok)
+              throw new Error(`Cannot inspect ${src}: HTTP ${response.status}`);
+            bytes = Buffer.from(await response.arrayBuffer());
+          } else {
+            const pathname = decodeURIComponent(
+              src.split(/[?#]/, 1)[0]
+            ).replace(/^\/+/, "");
+            const file = path2.resolve(publicRoot, pathname);
+            within(publicRoot, file);
+            within(await realpath(publicRoot), await realpath(file));
+            bytes = await readFile2(file);
+          }
+          const meta = await sharp(bytes, { animated: true }).metadata();
+          const swapped = (meta.orientation ?? 1) >= 5;
+          const width = swapped ? meta.height : meta.width;
+          const height = swapped ? meta.width : meta.pageHeight ?? meta.height;
+          if (!width || !height)
+            throw new Error(`Cannot inspect dimensions of ${src}`);
+          return {
+            url: src,
+            width,
+            height,
+            bytes: bytes.length,
+            format: meta.format,
+            progressive: meta.isProgressive ?? false,
+            alpha: Boolean(
+              meta.hasAlpha && ((meta.pages ?? 1) > 1 || !(await sharp(bytes).stats()).isOpaque)
+            ),
+            animated: (meta.pages ?? 1) > 1
+          };
+        })();
+        inspected.set(src, pending);
+      }
+      return pending;
+    };
+    var inspect = inspect2;
+    const entries = /* @__PURE__ */ new Map();
+    const explicit = [];
+    for (const input of iris.assets) {
+      const src = typeof input === "string" ? input : input.src;
+      if (/^https?:\/\//i.test(src)) {
+        if (fg2.isDynamicPattern(new URL(src).pathname))
+          return irisFailure(
+            "remote_pattern",
+            "Remote URLs must be explicit; a glob cannot enumerate a bucket"
+          );
+        explicit.push(input);
+      } else if (typeof input === "string" && fg2.isDynamicPattern(src.startsWith("/") ? src.split(/[?#]/, 1)[0] : src)) {
+        const files = await fg2(
+          src.startsWith("/") ? src.split(/[?#]/, 1)[0].slice(1) : src,
+          {
+            cwd: src.startsWith("/") ? publicRoot : rootDir,
+            onlyFiles: true,
+            followSymbolicLinks: false,
+            ignore: ["**/node_modules/**", "**/.git/**", "**/.next/**"]
+          }
+        );
+        for (const file of files.sort()) {
+          const full = path2.resolve(
+            src.startsWith("/") ? publicRoot : rootDir,
+            file
+          );
+          const relative = within(publicRoot, full);
+          const url = `/${relative.split(path2.sep).map(encodeURIComponent).join("/")}`;
+          entries.set(url, url);
+        }
+      } else explicit.push(input);
+    }
+    for (const input of explicit) {
+      const src = typeof input === "string" ? input : input.src;
+      entries.set(src, input);
+    }
+    const inspected = /* @__PURE__ */ new Map();
+    const catalog = [];
+    const identities = /* @__PURE__ */ new Set();
+    for (const input of entries.values()) {
+      const entry = typeof input === "string" ? { src: input } : input;
+      const metadata = "width" in entry ? entry : await inspect2(entry.src);
+      const { width, height, bytes, format, progressive, alpha, animated } = metadata;
+      const variants = await Promise.all(
+        (entry.variants ?? []).map(
+          (variant) => typeof variant === "string" ? inspect2(variant) : variant
+        )
+      );
+      if (!validVariant({ url: entry.src, width, height, bytes }) || !variants.every(validVariant))
+        return irisFailure("invalid_asset", `Invalid metadata for ${entry.src}`);
+      for (const identity of /* @__PURE__ */ new Set([entry.src, entry.id ?? entry.src])) {
+        if (identities.has(identity))
+          return irisFailure(
+            "duplicate_asset",
+            `Ambiguous asset identity: ${identity}`
+          );
+        identities.add(identity);
+      }
+      catalog.push({
+        src: entry.src,
+        id: entry.id,
+        width,
+        height,
+        bytes,
+        format,
+        progressive,
+        alpha,
+        animated,
+        variants,
+        placeholder: entry.placeholder,
+        placeholders: entry.placeholders
+      });
+    }
+    return { ok: true, data: catalog };
+  } catch (error) {
+    return irisFailure(
+      "prepare_failed",
+      error instanceof Error ? error.message : String(error)
+    );
+  }
+}
+function within(root, file) {
+  const relative = path2.relative(root, file);
+  if (relative === ".." || relative.startsWith(`..${path2.sep}`) || path2.isAbsolute(relative)) {
+    throw new Error(`Image source escapes publicDir: ${file}`);
+  }
+  return relative;
+}
+
+// packages/node/generate.ts
+async function generateIris({
+  iris,
+  generation,
+  rootDir = process.cwd(),
+  configFile = "iris.config.ts",
+  allowStale = false,
+  fetch: fetcher = fetch
+}) {
+  if (!generation.output?.trim())
+    throw new Error("Iris requires an output directory");
+  const directory = path3.resolve(rootDir, generation.output);
+  const publicDir = path3.resolve(rootDir, generation.publicDir ?? "public");
+  const adapter = generation.adapter !== false;
+  try {
+    const sources = await discoverIrisSources(
+      {
+        ...generation,
+        sources: [...iris.assets, ...generation.sources ?? []]
+      },
+      rootDir
+    );
+    const entries = /* @__PURE__ */ new Map();
+    for (const value of sources) {
+      const source = typeof value === "string" ? { src: value } : value;
+      const previous = entries.get(source.src);
+      entries.set(source.src, {
+        ...previous,
+        ...source,
+        optional: Boolean(
+          previous ? "optional" in previous && previous.optional && "optional" in source && source.optional : "optional" in source && source.optional
+        )
+      });
+    }
+    const catalog = {};
+    const placeholders = {};
+    const queue = [...entries.values()];
+    let skipped = 0;
+    let cursor = 0;
+    async function worker() {
+      while (cursor < queue.length) {
+        const source = queue[cursor++];
+        if ("width" in source) {
+          const prepared = await prepareIrisAssets({
+            iris: { assets: [source] },
+            rootDir,
+            publicDir,
+            fetch: fetcher
+          });
+          if (!prepared.ok) throw new Error(prepared.error.message);
+          catalog[source.src] = prepared.data[0];
+          if (source.placeholder) placeholders[source.src] = source.placeholder;
+          continue;
+        }
+        let bytes;
+        if (/^https?:\/\//i.test(source.src)) {
+          const response = await fetcher(source.src, {
+            signal: AbortSignal.timeout(3e4)
+          });
+          if (source.optional && response.status === 404) {
+            skipped++;
+            continue;
+          }
+          if (!response.ok)
+            throw new Error(`${response.status} fetching ${source.src}`);
+          bytes = Buffer.from(await response.arrayBuffer());
+        } else {
+          const pathname = decodeURIComponent(
+            source.src.split(/[?#]/, 1)[0]
+          ).replace(/^\/+/, "");
+          const file = path3.resolve(publicDir, pathname);
+          for (const relative of [
+            path3.relative(publicDir, file),
+            path3.relative(await realpath2(publicDir), await realpath2(file))
+          ]) {
+            if (relative === ".." || relative.startsWith(`..${path3.sep}`) || path3.isAbsolute(relative))
+              throw new Error(
+                `Iris local source escapes publicDir: ${source.src}`
+              );
+          }
+          bytes = await readFile3(file);
+        }
+        const meta = await sharp2(bytes, { animated: true }).metadata();
+        const swapped = (meta.orientation ?? 1) >= 5;
+        const width = swapped ? meta.height : meta.width;
+        const height = swapped ? meta.width : meta.pageHeight ?? meta.height;
+        if (!width || !height)
+          throw new Error(`Cannot inspect dimensions of ${source.src}`);
+        const placeholderOptions = source.placeholderOptions ?? {};
+        const format = placeholderOptions.format ?? "webp";
+        const size = placeholderOptions.width ?? 10;
+        const quality = placeholderOptions.quality ?? 40;
+        async function encodePlaceholder({
+          width: width2,
+          quality: quality2
+        }) {
+          const buffer = await sharp2(bytes, { page: 0, pages: 1 }).rotate().resize({
+            width: width2,
+            height: width2,
+            fit: "inside",
+            withoutEnlargement: true
+          }).toFormat(format, { quality: quality2 }).toBuffer();
+          return `data:image/${format};base64,${buffer.toString("base64")}`;
+        }
+        const placeholder = source.placeholder ?? await encodePlaceholder({ width: size, quality });
+        placeholders[source.src] = placeholder;
+        if (source.placeholderOnly) continue;
+        const preparedPlaceholders = [...source.placeholders ?? []];
+        for (const request of iris.placeholderRequests) {
+          if (preparedPlaceholders.some(
+            (item) => item.width === request.width && item.quality === request.quality
+          ))
+            continue;
+          const url = request.width === size && request.quality === quality ? placeholder : await encodePlaceholder(request);
+          preparedPlaceholders.push({ ...request, url });
+        }
+        const animated = (meta.pages ?? 1) > 1;
+        const alpha = Boolean(
+          meta.hasAlpha && (animated || !(await sharp2(bytes).stats()).isOpaque)
+        );
+        const metadata = {
+          src: source.src,
+          id: source.id,
+          width,
+          height,
+          bytes: bytes.length,
+          format: meta.format,
+          alpha,
+          animated,
+          progressive: meta.isProgressive ?? false,
+          placeholder,
+          placeholders: preparedPlaceholders,
+          variants: []
+        };
+        if (source.variants?.length) {
+          const prepared = await prepareIrisAssets({
+            iris: {
+              assets: [
+                { ...metadata, variants: [] },
+                ...source.variants.filter(
+                  (item) => typeof item === "string"
+                )
+              ]
+            },
+            rootDir,
+            publicDir,
+            fetch: fetcher
+          });
+          if (!prepared.ok) throw new Error(prepared.error.message);
+          metadata.variants = [
+            ...metadata.variants,
+            ...source.variants.map((variant) => {
+              if (typeof variant !== "string") return variant;
+              const asset = prepared.data.find((item) => item.src === variant);
+              return { ...asset, url: asset.src };
+            })
+          ];
+        }
+        catalog[source.src] = metadata;
+      }
+    }
+    const concurrency = generation.concurrency ?? 4;
+    if (!Number.isSafeInteger(concurrency) || concurrency < 1)
+      throw new Error("concurrency must be a positive integer");
+    await Promise.all(Array.from({ length: concurrency }, worker));
+    const sorted = (data) => Object.fromEntries(
+      Object.entries(data).sort(([a], [b]) => a.localeCompare(b))
+    );
+    const files = [
+      ["catalog.json", sorted(catalog)],
+      ["placeholders.json", sorted(placeholders)]
+    ];
+    if (generation.report)
+      files.push([
+        "report.json",
+        {
+          inspected: Object.keys(catalog).length,
+          skipped,
+          assets: Object.values(catalog).map((asset) => ({
+            src: asset.src,
+            result: iris.resolve({ asset })
+          }))
+        }
+      ]);
+    await mkdir(directory, { recursive: true });
+    for (const [name, data] of files)
+      await atomicWrite(
+        path3.join(directory, name),
+        JSON.stringify(data, null, 2) + "\n"
+      );
+    if (adapter) {
+      let configImport = path3.relative(directory, path3.resolve(rootDir, configFile)).split(path3.sep).join("/").replace(/\.[cm]?[jt]s$/, "");
+      if (!configImport.startsWith(".")) configImport = `./${configImport}`;
+      await atomicWrite(
+        path3.join(directory, "image.tsx"),
+        `"use client"
+
+// Generated by Iris. Do not edit.
+import { createIrisNextImage } from "@joycostudio/iris/next"
+import iris from ${JSON.stringify(configImport)}
+import catalog from "./catalog.json"
+
+export const IrisImage = createIrisNextImage({ iris, catalog })
+`
+      );
+    }
+    return {
+      stale: false,
+      placeholders: Object.keys(placeholders).length,
+      inspected: Object.keys(catalog).length,
+      skipped
+    };
+  } catch (error) {
+    if (allowStale && await usableOutput({ directory, adapter })) {
+      console.warn("Iris generation failed; keeping existing files:", error);
+      return { stale: true, placeholders: 0, inspected: 0, skipped: 0 };
+    }
+    throw error;
+  }
+}
+async function atomicWrite(file, content) {
+  await writeFile(`${file}.tmp`, content);
+  await rename(`${file}.tmp`, file);
+}
+async function usableOutput({
+  directory,
+  adapter
+}) {
+  try {
+    const catalog = JSON.parse(
+      await readFile3(path3.join(directory, "catalog.json"), "utf8")
+    );
+    const placeholders = JSON.parse(
+      await readFile3(path3.join(directory, "placeholders.json"), "utf8")
+    );
+    if (!catalog || Array.isArray(catalog) || !Object.keys(catalog).length || !placeholders || Array.isArray(placeholders))
+      return false;
+    if (adapter && !(await readFile3(path3.join(directory, "image.tsx"), "utf8")).includes(
+      "createIrisNextImage"
+    ))
+      return false;
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// packages/cli/index.ts
+var args = process.argv.slice(2);
+void main().catch((error) => {
+  console.error(error);
+  process.exitCode = 1;
+});
+async function main() {
+  const command = args.find((argument) => !argument.startsWith("-"));
+  if (!command || command === "help" || args.includes("--help") || args.includes("-h")) {
+    printHelp();
+  } else if (command === "init") {
+    await runInit();
+  } else if (command === "generate") {
+    await runGenerate();
+  } else {
+    throw new Error(`Unknown Iris command: ${command}`);
+  }
+}
+async function runInit() {
+  const rootDir = process.cwd();
+  const existing = await findExistingConfig(rootDir);
+  if (existing) {
+    console.log(`${path4.basename(existing)} already exists; left unchanged.`);
+    return;
+  }
+  await writeFile2(path4.join(rootDir, "iris.config.ts"), initialConfig, {
+    flag: "wx"
+  });
+  console.log("Created iris.config.ts.");
+  console.log(
+    "Review sources and scan in iris.config.ts, then run iris generate."
+  );
+}
+var initialConfig = `import { createIris } from "@joycostudio/iris"
+
+export default createIris({
+  assets: ["public/**/*.{png,jpg,jpeg,webp,avif,gif}"],
+  recipes: {
+    direct: { preview: "none" },
+    blur: { placeholder: "blur" },
+  },
+  rules: [{ when: { priority: true }, recipe: "direct" }],
+  fallback: "blur",
+})
+
+export const generate = { output: "src/generated/iris" }
+`;
+async function runGenerate() {
+  const rootDir = process.cwd();
+  const configArgument = optionValue("--config");
+  const configPath = configArgument ? path4.resolve(rootDir, configArgument) : await findConfig(rootDir);
+  const jiti = createJiti(process.cwd(), { interopDefault: false });
+  const imported = await jiti.import(configPath);
+  const iris = imported.default;
+  if (!iris || typeof iris.select !== "function" || typeof iris.resolve !== "function")
+    throw new Error(
+      `${path4.relative(rootDir, configPath)} must default-export createIris(...)`
+    );
+  const generation = typeof imported.generate === "function" ? await imported.generate() : imported.generate ?? { output: "src/generated/iris" };
+  const result = await generateIris({
+    iris,
+    generation,
+    rootDir,
+    configFile: configPath,
+    allowStale: args.includes("--allow-stale")
+  });
+  if (result.stale) console.log("Iris kept existing generated files.");
+  else
+    console.log(
+      `Iris prepared ${result.inspected} assets and ${result.placeholders} placeholders; skipped ${result.skipped} optional sources.`
+    );
+}
+async function findConfig(rootDir) {
+  const existing = await findExistingConfig(rootDir);
+  if (existing) return existing;
+  throw new Error(
+    "Iris could not find iris.config.ts (or .mts/.js/.mjs). Run iris init first."
+  );
+}
+async function findExistingConfig(rootDir) {
+  for (const name of [
+    "iris.config.ts",
+    "iris.config.mts",
+    "iris.config.js",
+    "iris.config.mjs"
+  ]) {
+    const candidate = path4.join(rootDir, name);
+    try {
+      await access(candidate);
+      return candidate;
+    } catch (error) {
+      if (error.code !== "ENOENT") throw error;
+    }
+  }
+  return null;
+}
+function optionValue(name) {
+  const index = args.indexOf(name);
+  return index < 0 ? void 0 : args[index + 1];
+}
+function printHelp() {
+  console.log(`Iris responsive-image tooling
+
+Usage:
+  iris init
+  iris generate [--config path] [--allow-stale]
+
+Commands:
+  init       Create a default iris.config.ts without replacing existing config
+  generate   Discover sources from iris.config and write image manifests
+`);
+}
+//# sourceMappingURL=cli.js.map