img-subir 0.0.1

package/dist/index.d.ts

@@ -0,0 +1,215 @@
+type RasterFormat = "png" | "jpeg" | "webp" | "avif" | "gif";
+type Format = RasterFormat | "svg";
+type Kind = "ui" | "photo" | "graphic";
+type PresetName = "web" | "github" | "screenshot" | "og" | "thumb" | "lossless";
+type FormatChoice = "auto" | "keep" | RasterFormat;
+type Status = "optimized" | "kept" | "failed" | "budget-missed";
+interface Preset {
+    name: PresetName;
+    /** Longest allowed width in px (undefined = no limit). */
+    maxWidth?: number;
+    maxHeight?: number;
+    /** Output formats that may be tried. */
+    candidates: RasterFormat[];
+    /** SSIM floor per kind. Lossy candidates below this are rejected. */
+    floor: Record<Kind, number>;
+    /** Starting quality per lossy format, per kind. */
+    quality: Record<Kind, {
+        webp: number;
+        avif: number;
+        jpeg: number;
+        png: number;
+    }>;
+    /** Only keep AVIF if it is at least this fraction smaller than the best non-AVIF candidate. */
+    avifMinGain: number;
+    /** Skip AVIF above this many pixels (encode time grows fast). */
+    avifMaxPixels: number;
+    /** Also try lossless WebP for ui/graphic kinds. */
+    losslessWebp: boolean;
+    /** Only lossless candidates; no resize. */
+    lossless: boolean;
+    /** Force a kind for every file. */
+    forceKind?: Kind;
+    /** Don't rewrite if gain is below this percent. */
+    minGainPercent: number;
+    /** Notes shown in `img-subir presets`. */
+    note: string;
+}
+interface OptimizeOptions {
+    /** Files, directories or globs. */
+    paths: string[];
+    cwd?: string;
+    preset?: PresetName;
+    format?: FormatChoice;
+    kind?: "auto" | Kind;
+    maxWidth?: number;
+    maxHeight?: number;
+    quality?: number;
+    targetKb?: number;
+    /** Write into this directory (mirrors structure) instead of in place. */
+    out?: string;
+    /** Inserted before the extension, e.g. ".min". */
+    suffix?: string;
+    /** Keep originals in .img-subir-originals/ (default true). */
+    backup?: boolean;
+    /** Change the extension when the format changes (default true). */
+    rename?: boolean;
+    /** Update references in text files. true = default globs; string[] = custom globs. */
+    rewriteRefs?: boolean | string[];
+    dryRun?: boolean;
+    /** Skip SSIM checks; use fixed qualities. */
+    fast?: boolean;
+    concurrency?: number;
+    /** Per-file progress callback. */
+    onFile?: (result: FileResult) => void;
+}
+interface ImageInfo {
+    path: string;
+    format: Format;
+    width: number;
+    height: number;
+    bytes: number;
+    hasAlpha: boolean;
+    animated: boolean;
+}
+interface OutputInfo {
+    path: string;
+    format: Format;
+    width: number;
+    height: number;
+    bytes: number;
+    quality?: number;
+    lossless?: boolean;
+}
+interface Candidate {
+    format: Format;
+    bytes: number;
+    quality?: number;
+    lossless?: boolean;
+    ssim?: number;
+    passed: boolean;
+}
+interface FileResult {
+    input: ImageInfo;
+    output: OutputInfo | null;
+    kind: Kind | "svg" | "animated";
+    status: Status;
+    savedBytes: number;
+    savedPercent: number;
+    actions: string[];
+    candidates: Candidate[];
+    reason?: string;
+    error?: string;
+    /** Where the original went (backup path), if moved. */
+    backupPath?: string;
+    /** With --out, kept files are copied unchanged to their mirrored path. */
+    copiedTo?: string;
+    durationMs: number;
+}
+interface Rename {
+    from: string;
+    to: string;
+}
+interface RewrittenRef {
+    file: string;
+    from: string;
+    to: string;
+    count: number;
+}
+interface Totals {
+    files: number;
+    inputBytes: number;
+    outputBytes: number;
+    savedBytes: number;
+    savedPercent: number;
+    optimized: number;
+    kept: number;
+    failed: number;
+    budgetMissed: number;
+    durationMs: number;
+}
+interface Report {
+    schemaVersion: 1;
+    version: string;
+    preset: PresetName;
+    dryRun: boolean;
+    files: FileResult[];
+    totals: Totals;
+    renamed: Rename[];
+    rewrittenRefs: RewrittenRef[];
+    backupDirs: string[];
+}
+interface InspectResult {
+    input: ImageInfo;
+    kind: Kind | "svg" | "animated";
+    plan: {
+        targetWidth: number;
+        targetHeight: number;
+        candidates: string[];
+        floor: number | null;
+    };
+}
+
+declare function optimize(options: OptimizeOptions): Promise<Report>;
+declare function inspect(paths: string[], options?: Omit<OptimizeOptions, "paths">): Promise<InspectResult[]>;
+declare function fmtBytes(n: number): string;
+
+declare const presets: Record<PresetName, Preset>;
+declare const presetNames: PresetName[];
+declare function getPreset(name: string | undefined): Preset;
+
+declare const DEFAULT_REF_GLOBS: string[];
+/**
+ * Rewrites references to renamed files inside text files under `roots`.
+ * Only whole-token matches are replaced, so `logo.png` never matches `logo.png.bak` or `mylogo.png`.
+ */
+declare function rewriteRefs(renamed: Rename[], roots: string[], globs?: string[], dryRun?: boolean): Promise<RewrittenRef[]>;
+
+declare const BACKUP_DIR = ".img-subir-originals";
+interface Discovered {
+    files: string[];
+    /** Directories the user passed (used as rewrite roots). */
+    roots: string[];
+}
+/**
+ * @param excludeDirs absolute directories whose contents are skipped (e.g. the --out dir when it sits inside an input dir)
+ */
+declare function discover(inputs: string[], cwd: string, excludeDirs?: string[]): Promise<Discovered>;
+
+declare function probe(filePath: string): Promise<ImageInfo>;
+
+interface ClassifyStats {
+    distinctColors: number;
+    flatShare: number;
+    /** Share of sampled pixels that are not fully opaque. 0 means the alpha channel is unused. */
+    transparentShare: number;
+    score: number;
+}
+/**
+ * Cheap heuristics, no ML. Samples a 256px thumbnail and measures how "flat" it is.
+ * UI screenshots: few distinct colors, long runs of identical pixels.
+ * Photos: the opposite.
+ */
+declare function classify(info: ImageInfo, input?: string | Buffer): Promise<{
+    kind: Kind;
+    stats: ClassifyStats;
+}>;
+
+type FileConfig = Partial<Omit<OptimizeOptions, "paths" | "cwd" | "onFile">>;
+/**
+ * Looks in cwd and its ancestors for a config file or a package.json "img-subir" key.
+ * A malformed config is an error, not a silent fallback to defaults.
+ */
+declare function loadConfig(cwd: string): Promise<{
+    config: FileConfig;
+    source?: string;
+}>;
+
+declare const VERSION: string;
+
+/** Thrown for bad invocations (unknown preset, missing path, invalid flag). The CLI maps it to exit code 2. */
+declare class UsageError extends Error {
+    name: string;
+}
+
+export { BACKUP_DIR, type Candidate, DEFAULT_REF_GLOBS, type FileResult, type Format, type FormatChoice, type ImageInfo, type InspectResult, type Kind, type OptimizeOptions, type OutputInfo, type Preset, type PresetName, type RasterFormat, type Rename, type Report, type RewrittenRef, type Status, type Totals, UsageError, VERSION, classify, discover, fmtBytes, getPreset, inspect, loadConfig, optimize, presetNames, presets, probe, rewriteRefs };

package/dist/index.js

@@ -0,0 +1,35 @@
+import {
+  BACKUP_DIR,
+  DEFAULT_REF_GLOBS,
+  UsageError,
+  VERSION,
+  classify,
+  discover,
+  fmtBytes,
+  getPreset,
+  inspect,
+  loadConfig,
+  optimize,
+  presetNames,
+  presets,
+  probe,
+  rewriteRefs
+} from "./chunk-CWZBNFPK.js";
+export {
+  BACKUP_DIR,
+  DEFAULT_REF_GLOBS,
+  UsageError,
+  VERSION,
+  classify,
+  discover,
+  fmtBytes,
+  getPreset,
+  inspect,
+  loadConfig,
+  optimize,
+  presetNames,
+  presets,
+  probe,
+  rewriteRefs
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "img-subir",
+  "version": "0.0.1",
+  "description": "Agent-friendly CLI that optimizes images (PNG/JPEG/WebP/AVIF/GIF/SVG) for websites, READMEs and Subir pages.",
+  "keywords": [
+    "image",
+    "optimize",
+    "compress",
+    "webp",
+    "avif",
+    "sharp",
+    "svgo",
+    "cli",
+    "agent",
+    "screenshots"
+  ],
+  "license": "MIT",
+  "type": "module",
+  "engines": {
+    "node": ">=20"
+  },
+  "bin": {
+    "img-subir": "dist/cli.js"
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "skills",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsx src/cli.ts",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "pnpm build && pnpm test"
+  },
+  "dependencies": {
+    "citty": "^0.2.2",
+    "fast-glob": "^3.3.3",
+    "picocolors": "^1.1.1",
+    "sharp": "^0.35.4",
+    "ssim.js": "^3.5.0",
+    "svgo": "^4.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^26.6.2",
+    "tsup": "^8.5.1",
+    "tsx": "^4.23.15",
+    "typescript": "^5.9.3",
+    "vitest": "^5.0.1"
+  }
+}

package/skills/img-subir/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: img-subir
+description: Optimize images (PNG, JPEG, WebP, AVIF, GIF, SVG) for websites, READMEs, docs and Subir pages. Use before uploading or committing screenshots, marketing images or any raster/SVG assets. Cuts file size 70–95% with no visible loss, downsizes Retina screenshots, strips metadata, and can rewrite <img src> references when extensions change.
+---
+
+# img-subir
+
+Shrinks images so pages load fast and repos stay small. Non-interactive, safe to run blind.
+
+## When to use
+
+- Before `subir upload`, before committing images to a repo, before adding screenshots to a README or PR.
+- Whenever a directory contains `.png`, `.jpg`, `.gif` or `.svg` files larger than ~200 KB.
+
+## Commands
+
+```bash
+npx img-subir <paths...> --json                  # website / Subir page (preset: web)
+npx img-subir <paths...> --preset github --json  # README / PR screenshots (never AVIF)
+npx img-subir <paths...> --rewrite-refs --json   # also fix src/href in html/md/tsx/css that point at renamed files
+npx img-subir <paths...> --dry-run               # preview only
+npx img-subir inspect <paths...>                 # what would happen, no writes
+npx img-subir doctor                             # verify encoders on this machine
+```
+
+`<paths>` can be files, directories or globs. Directories are scanned recursively.
+
+## Defaults you should know
+
+- Writes **in place**. Originals are moved to `.img-subir-originals/` next to them. Delete or ignore that folder before uploading/committing. Never re-run on it.
+- Extensions change when the format changes (`shot.png` → `shot.webp`). Read `renamed[]` in the JSON and update references, or pass `--rewrite-refs`.
+- Never writes a file that is larger than the input. Those show as `status: "kept"` with a `reason`. Kept is not an error.
+- Retina screenshots are downscaled to 1920px (web) / 1600px (github). Pass `--max-width` to change.
+- Metadata (EXIF, GPS, thumbnails) is always stripped.
+
+## Reading the JSON
+
+```jsonc
+{
+  "files": [{ "input": {...}, "output": {...} | null, "status": "optimized|kept|failed|budget-missed", "savedPercent": 95.7, "actions": [...], "reason": "..." }],
+  "totals": { "inputBytes": 0, "outputBytes": 0, "savedPercent": 0, "optimized": 0, "kept": 0, "failed": 0 },
+  "renamed": [{ "from": "/abs/a.png", "to": "/abs/a.webp" }],
+  "rewrittenRefs": [{ "file": "/abs/index.html", "from": "...", "to": "...", "count": 2 }],
+  "backupDirs": ["/abs/assets/.img-subir-originals"]
+}
+```
+
+Exit codes: `0` ok · `1` a file failed (others still written) · `2` bad flags · `3` `--target-kb` could not be met within the quality floor (best effort was written; tell the user the size reached).
+
+## Rules
+
+- Do not pass `--no-backup` unless the user asked for it.
+- For social/OG cards use `--preset og` (JPEG/PNG only). For pixel-exact needs use `--preset lossless`.
+- If output looks blurry to the user, re-run with `--preset screenshot` or `--kind ui`.
+- Use `--out <dir>` when the user wants originals untouched; kept files are copied there too (`copiedTo`), so the output tree is complete. `--out` may not be the input directory itself.
+- Unknown flags, missing values and malformed config exit with code 2 before touching any file.