@1aboveio/skills 0.0.0-stage → 1.0.0

package/skills/content/image-gen/scripts/options.mjs

@@ -0,0 +1,293 @@
+/**
+ * Argument parsing and option mapping.
+ *
+ * These are pure functions so the awkward cases — a misspelled flag, a size the
+ * provider cannot express, a response whose bytes do not match the filename —
+ * can be tested without touching the network.
+ */
+
+export const OPENAI_SIZES = ['1024x1024', '1536x1024', '1024x1536', 'auto'];
+export const QUALITIES = ['low', 'medium', 'high', 'auto'];
+
+// Exactly the set the Gemini API reports when it rejects an invalid ratio.
+// Verified against generativelanguage.googleapis.com rather than assumed.
+export const GEMINI_ASPECT_RATIOS = [
+  '1:1', '1:4', '1:8', '2:3', '3:2', '3:4', '4:1',
+  '4:3', '4:5', '5:4', '8:1', '9:16', '16:9', '21:9',
+];
+
+export const FLAG_SPEC = {
+  provider: { values: ['openai', 'gemini'] },
+  model: {},
+  size: {},
+  quality: { values: QUALITIES, onlyFor: 'openai' },
+  output: {},
+};
+
+const KNOWN_FLAGS = Object.keys(FLAG_SPEC);
+
+function suggestFlag(name) {
+  // Cheap edit-distance-ish match: a typo usually shares a prefix or most letters.
+  const candidates = KNOWN_FLAGS.filter(
+    (known) => known[0] === name[0] && Math.abs(known.length - name.length) <= 2,
+  );
+  if (!candidates.length) return undefined;
+  const score = (known) => [...new Set(name)].filter((ch) => known.includes(ch)).length;
+  return candidates.sort((a, b) => score(b) - score(a))[0];
+}
+
+/**
+ * Parse argv into a prompt plus flags.
+ *
+ * Unknown flags are errors rather than silent no-ops: a misspelled `--qualtiy`
+ * that is quietly dropped produces an image at the wrong setting and no hint of
+ * why, which is worse than refusing to run.
+ *
+ * @returns {{prompt: string, flags: object, errors: string[], warnings: string[]}}
+ */
+export function parseArgs(argv) {
+  const flags = {};
+  const positional = [];
+  const errors = [];
+  const warnings = [];
+
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (!arg.startsWith('--')) {
+      positional.push(arg);
+      continue;
+    }
+
+    const body = arg.slice(2);
+    const eq = body.indexOf('=');
+    const name = eq >= 0 ? body.slice(0, eq) : body;
+    let value = eq >= 0 ? body.slice(eq + 1) : undefined;
+
+    if (!Object.hasOwn(FLAG_SPEC, name)) {
+      const suggestion = suggestFlag(name);
+      errors.push(`Unknown option --${name}.${suggestion ? ` Did you mean --${suggestion}?` : ''}`);
+      if (value === undefined && argv[i + 1] && !argv[i + 1].startsWith('--')) i++;
+      continue;
+    }
+
+    if (value === undefined) {
+      const next = argv[i + 1];
+      // A flag swallowing the next flag as its value is how `--quality --output x`
+      // silently loses the output path, so treat it as missing instead.
+      if (next === undefined || next.startsWith('--')) {
+        errors.push(`Option --${name} needs a value.`);
+        continue;
+      }
+      value = next;
+      i++;
+    }
+
+    const allowed = FLAG_SPEC[name].values;
+    if (allowed && !allowed.includes(value)) {
+      errors.push(`Invalid --${name} "${value}". Valid options: ${allowed.join(', ')}`);
+      continue;
+    }
+
+    flags[name] = value;
+  }
+
+  const provider = flags.provider || 'openai';
+  for (const [name, spec] of Object.entries(FLAG_SPEC)) {
+    if (spec.onlyFor && flags[name] !== undefined && spec.onlyFor !== provider) {
+      warnings.push(`--${name} applies to ${spec.onlyFor} only; ignoring it for ${provider}.`);
+      delete flags[name];
+    }
+  }
+
+  return { prompt: positional.join(' ').trim(), flags, errors, warnings };
+}
+
+/**
+ * Validate a size for the OpenAI image endpoint, which takes literal pixel
+ * dimensions.
+ */
+export function openAiSize(size) {
+  if (!size) return { value: '1024x1024' };
+  if (OPENAI_SIZES.includes(size)) return { value: size };
+  return { error: `Invalid size "${size}". Valid options: ${OPENAI_SIZES.join(', ')}` };
+}
+
+/**
+ * Map a `--size` to a Gemini aspect ratio.
+ *
+ * Gemini has no pixel-dimension parameter — it takes a ratio — so a WxH size is
+ * snapped to the closest ratio it supports rather than rejected. Without this the
+ * flag was accepted and silently discarded, and every Gemini image came back
+ * square no matter what was asked for.
+ *
+ * @returns {{value?: string, error?: string, snappedFrom?: string}}
+ *   `value` undefined means "send no ratio and let the model default".
+ */
+export function geminiAspectRatio(size) {
+  if (!size || size === 'auto') return {};
+  if (GEMINI_ASPECT_RATIOS.includes(size)) return { value: size };
+
+  const ratioMatch = /^(\d+):(\d+)$/.exec(size);
+  if (ratioMatch) {
+    return {
+      error:
+        `Gemini does not support the aspect ratio "${size}". ` +
+        `Valid ratios: ${GEMINI_ASPECT_RATIOS.join(', ')}`,
+    };
+  }
+
+  const pixelMatch = /^(\d+)x(\d+)$/i.exec(size);
+  if (!pixelMatch) {
+    return {
+      error:
+        `Invalid size "${size}". Use WxH (e.g. 1536x1024) or an aspect ratio ` +
+        `(${GEMINI_ASPECT_RATIOS.join(', ')}).`,
+    };
+  }
+
+  const width = Number(pixelMatch[1]);
+  const height = Number(pixelMatch[2]);
+  if (!width || !height) return { error: `Invalid size "${size}": zero dimension.` };
+
+  // Compare in log space so 2:1 and 1:2 are equally far from 1:1.
+  const target = Math.log(width / height);
+  let best;
+  for (const ratio of GEMINI_ASPECT_RATIOS) {
+    const [w, h] = ratio.split(':').map(Number);
+    const distance = Math.abs(Math.log(w / h) - target);
+    if (!best || distance < best.distance) best = { ratio, distance };
+  }
+
+  return best.ratio === '1:1' && best.distance === 0
+    ? { value: '1:1' }
+    : { value: best.ratio, snappedFrom: size };
+}
+
+/**
+ * Read pixel dimensions out of the returned bytes.
+ *
+ * Providers and proxies do not always honor the requested size — a gateway was
+ * observed returning 1402x1122 for a 1024x1536 request — and a silent mismatch
+ * is invisible until someone opens the file. Reading the header costs nothing and
+ * turns that into a printed fact.
+ *
+ * @returns {{width: number, height: number} | null} null when the format is not
+ *   one this recognizes, which is a reason to stay quiet rather than to warn.
+ */
+export function imageDimensions(buffer) {
+  if (!buffer || buffer.length < 24) return null;
+
+  if (buffer.readUInt32BE(0) === 0x89504e47) {
+    return { width: buffer.readUInt32BE(16), height: buffer.readUInt32BE(20) };
+  }
+
+  if (buffer[0] === 0xff && buffer[1] === 0xd8) {
+    let offset = 2;
+    while (offset + 9 < buffer.length) {
+      if (buffer[offset] !== 0xff) {
+        offset += 1;
+        continue;
+      }
+      const marker = buffer[offset + 1];
+      const isStartOfFrame =
+        (marker >= 0xc0 && marker <= 0xc3) ||
+        (marker >= 0xc5 && marker <= 0xc7) ||
+        (marker >= 0xc9 && marker <= 0xcb) ||
+        (marker >= 0xcd && marker <= 0xcf);
+      if (isStartOfFrame) {
+        return { width: buffer.readUInt16BE(offset + 7), height: buffer.readUInt16BE(offset + 5) };
+      }
+      if (marker === 0xd8 || marker === 0x01 || (marker >= 0xd0 && marker <= 0xd7)) {
+        offset += 2;
+        continue;
+      }
+      offset += 2 + buffer.readUInt16BE(offset + 2);
+    }
+    return null;
+  }
+
+  if (buffer.length >= 30 && buffer.toString('ascii', 0, 4) === 'RIFF' && buffer.toString('ascii', 8, 12) === 'WEBP') {
+    const chunk = buffer.toString('ascii', 12, 16);
+    if (chunk === 'VP8X') {
+      return {
+        width: buffer.readUIntLE(24, 3) + 1,
+        height: buffer.readUIntLE(27, 3) + 1,
+      };
+    }
+    if (chunk === 'VP8 ') {
+      return {
+        width: buffer.readUInt16LE(26) & 0x3fff,
+        height: buffer.readUInt16LE(28) & 0x3fff,
+      };
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Compare what was asked for against what arrived.
+ *
+ * @returns {string | undefined} a warning when they disagree meaningfully.
+ */
+export function describeSizeMismatch({ requestedSize, aspectRatio, actual }) {
+  if (!actual) return undefined;
+
+  const pixels = requestedSize && /^(\d+)x(\d+)$/i.exec(requestedSize);
+  if (pixels) {
+    const [width, height] = [Number(pixels[1]), Number(pixels[2])];
+    if (width !== actual.width || height !== actual.height) {
+      return `Requested ${width}x${height} but the provider returned ${actual.width}x${actual.height}.`;
+    }
+    return undefined;
+  }
+
+  if (aspectRatio) {
+    const [w, h] = aspectRatio.split(':').map(Number);
+    const wanted = w / h;
+    const got = actual.width / actual.height;
+    // 2% covers rounding to whole pixels without hiding a real substitution.
+    if (Math.abs(Math.log(got / wanted)) > 0.02) {
+      return `Requested aspect ratio ${aspectRatio} but the provider returned ${actual.width}x${actual.height}.`;
+    }
+  }
+
+  return undefined;
+}
+
+const MIME_EXTENSIONS = {
+  'image/png': '.png',
+  'image/jpeg': '.jpg',
+  'image/jpg': '.jpg',
+  'image/webp': '.webp',
+  'image/gif': '.gif',
+};
+
+/** The file extension matching the bytes a provider actually returned. */
+export function extensionForMimeType(mimeType) {
+  if (!mimeType) return '.png';
+  return MIME_EXTENSIONS[mimeType.split(';')[0].trim().toLowerCase()] ?? '.png';
+}
+
+/**
+ * Decide where to write, given what the provider returned.
+ *
+ * An explicit --output is always honored — overriding the user's chosen path
+ * would be worse than a wrong extension — but a mismatch is worth saying out
+ * loud, since a JPEG named .png breaks some viewers and upload validators.
+ *
+ * @returns {{path: string, warning?: string}}
+ */
+export function resolveOutputPath({ requested, defaultBase, mimeType }) {
+  const extension = extensionForMimeType(mimeType);
+  if (!requested) return { path: `${defaultBase}${extension}` };
+
+  const currentExtension = /\.[A-Za-z0-9]+$/.exec(requested)?.[0]?.toLowerCase();
+  if (currentExtension && currentExtension !== extension) {
+    return {
+      path: requested,
+      warning: `Saved ${mimeType} bytes to ${requested}; the extension says ${currentExtension}.`,
+    };
+  }
+  return { path: currentExtension ? requested : `${requested}${extension}` };
+}

package/skills/content/image-gen/scripts/options.test.mjs

@@ -0,0 +1,245 @@
+import assert from 'node:assert/strict';
+import { describe, it } from 'node:test';
+
+import {
+  GEMINI_ASPECT_RATIOS,
+  describeSizeMismatch,
+  extensionForMimeType,
+  imageDimensions,
+  geminiAspectRatio,
+  openAiSize,
+  parseArgs,
+  resolveOutputPath,
+} from './options.mjs';
+
+describe('parseArgs', () => {
+  it('joins the positional words into the prompt', () => {
+    const { prompt, errors } = parseArgs(['a', 'red', 'fox']);
+
+    assert.equal(prompt, 'a red fox');
+    assert.deepEqual(errors, []);
+  });
+
+  it('accepts --flag value and --flag=value alike', () => {
+    assert.equal(parseArgs(['p', '--model', 'm']).flags.model, 'm');
+    assert.equal(parseArgs(['p', '--model=m']).flags.model, 'm');
+  });
+
+  it('rejects an unknown flag instead of ignoring it', () => {
+    // The old parser accepted --qualtiy silently and generated at the default.
+    const { errors } = parseArgs(['p', '--qualtiy', 'high']);
+
+    assert.equal(errors.length, 1);
+    assert.match(errors[0], /Unknown option --qualtiy/);
+  });
+
+  it('suggests the intended flag for a near miss', () => {
+    assert.match(parseArgs(['p', '--outpt', 'x.png']).errors[0], /Did you mean --output\?/);
+  });
+
+  it('does not let a flag swallow the next flag as its value', () => {
+    // `--quality --output x.png` used to set quality="--output" and lose the path.
+    const { flags, errors } = parseArgs(['p', '--quality', '--output', 'x.png']);
+
+    assert.match(errors[0], /--quality needs a value/);
+    assert.equal(flags.output, 'x.png');
+  });
+
+  it('reports a trailing flag with no value', () => {
+    assert.match(parseArgs(['p', '--output']).errors[0], /--output needs a value/);
+  });
+
+  it('validates enumerated flag values', () => {
+    assert.match(parseArgs(['p', '--provider', 'midjourney']).errors[0], /Invalid --provider/);
+    assert.match(parseArgs(['p', '--quality', 'ultra']).errors[0], /Invalid --quality/);
+  });
+
+  it('warns and drops a flag that does not apply to the chosen provider', () => {
+    const { flags, warnings } = parseArgs(['p', '--provider', 'gemini', '--quality', 'high']);
+
+    assert.equal(flags.quality, undefined);
+    assert.match(warnings[0], /--quality applies to openai only/);
+  });
+
+  it('keeps provider-specific flags when the provider does match', () => {
+    assert.equal(parseArgs(['p', '--quality', 'high']).flags.quality, 'high');
+  });
+});
+
+describe('openAiSize', () => {
+  it('defaults to a square', () => {
+    assert.equal(openAiSize(undefined).value, '1024x1024');
+  });
+
+  it('accepts the documented sizes and rejects others', () => {
+    assert.equal(openAiSize('1536x1024').value, '1536x1024');
+    assert.match(openAiSize('800x600').error, /Invalid size/);
+  });
+});
+
+describe('geminiAspectRatio', () => {
+  it('sends nothing when no size is given', () => {
+    assert.equal(geminiAspectRatio(undefined).value, undefined);
+    assert.equal(geminiAspectRatio('auto').value, undefined);
+  });
+
+  it('passes a supported ratio straight through', () => {
+    assert.equal(geminiAspectRatio('16:9').value, '16:9');
+  });
+
+  it('snaps pixel dimensions to the nearest supported ratio', () => {
+    // This is the whole point: --size used to be discarded for Gemini.
+    assert.equal(geminiAspectRatio('1536x1024').value, '3:2');
+    assert.equal(geminiAspectRatio('1024x1536').value, '2:3');
+    assert.equal(geminiAspectRatio('1920x1080').value, '16:9');
+    assert.equal(geminiAspectRatio('1024x1024').value, '1:1');
+  });
+
+  it('reports what it snapped away from, so the change is visible', () => {
+    const snapped = geminiAspectRatio('1000x500');
+
+    // 2:1 is not supported; 16:9 is the closest thing to it that is.
+    assert.equal(snapped.value, '16:9');
+    assert.equal(snapped.snappedFrom, '1000x500');
+  });
+
+  it('treats an exact square as exact, not snapped', () => {
+    assert.equal(geminiAspectRatio('1024x1024').snappedFrom, undefined);
+  });
+
+  it('rejects a well-formed ratio the API does not support', () => {
+    const rejected = geminiAspectRatio('7:5');
+
+    assert.match(rejected.error, /does not support the aspect ratio "7:5"/);
+    assert.match(rejected.error, /16:9/);
+  });
+
+  it('rejects unparseable sizes and zero dimensions', () => {
+    assert.match(geminiAspectRatio('huge').error, /Invalid size/);
+    assert.match(geminiAspectRatio('0x100').error, /zero dimension/);
+  });
+
+  it('only ever emits ratios the API accepts', () => {
+    for (const size of ['1536x1024', '1024x1536', '1920x1080', '100x800', '800x100']) {
+      assert.ok(GEMINI_ASPECT_RATIOS.includes(geminiAspectRatio(size).value), size);
+    }
+  });
+});
+
+describe('extensionForMimeType', () => {
+  it('maps the image types a provider may return', () => {
+    assert.equal(extensionForMimeType('image/png'), '.png');
+    assert.equal(extensionForMimeType('image/jpeg'), '.jpg');
+    assert.equal(extensionForMimeType('image/webp'), '.webp');
+  });
+
+  it('ignores charset parameters and casing', () => {
+    assert.equal(extensionForMimeType('IMAGE/JPEG; charset=binary'), '.jpg');
+  });
+
+  it('falls back to .png for anything unrecognized', () => {
+    assert.equal(extensionForMimeType(undefined), '.png');
+    assert.equal(extensionForMimeType('application/octet-stream'), '.png');
+  });
+});
+
+describe('resolveOutputPath', () => {
+  it('names the default file after the bytes actually returned', () => {
+    const resolved = resolveOutputPath({ defaultBase: './generated-1', mimeType: 'image/jpeg' });
+
+    assert.equal(resolved.path, './generated-1.jpg');
+    assert.equal(resolved.warning, undefined);
+  });
+
+  it('honors an explicit path but flags an extension mismatch', () => {
+    const resolved = resolveOutputPath({ requested: 'logo.png', mimeType: 'image/webp' });
+
+    assert.equal(resolved.path, 'logo.png');
+    assert.match(resolved.warning, /image\/webp/);
+  });
+
+  it('stays quiet when the extension already matches', () => {
+    assert.equal(resolveOutputPath({ requested: 'logo.png', mimeType: 'image/png' }).warning, undefined);
+  });
+
+  it('appends an extension when the requested path has none', () => {
+    assert.equal(resolveOutputPath({ requested: 'logo', mimeType: 'image/png' }).path, 'logo.png');
+  });
+});
+
+describe('imageDimensions', () => {
+  const png = (w, h) => {
+    const b = Buffer.alloc(24);
+    b.writeUInt32BE(0x89504e47, 0);
+    b.writeUInt32BE(w, 16);
+    b.writeUInt32BE(h, 20);
+    return b;
+  };
+
+  it('reads PNG dimensions', () => {
+    assert.deepEqual(imageDimensions(png(1536, 1024)), { width: 1536, height: 1024 });
+  });
+
+  it('reads JPEG dimensions from the start-of-frame marker', () => {
+    const b = Buffer.alloc(32, 0);
+    b[0] = 0xff; b[1] = 0xd8;          // SOI
+    b[2] = 0xff; b[3] = 0xe0;          // APP0, skipped via its length
+    b.writeUInt16BE(6, 4);
+    b[10] = 0xff; b[11] = 0xc0;        // SOF0
+    b.writeUInt16BE(17, 12);
+    b.writeUInt16BE(480, 15);          // height
+    b.writeUInt16BE(640, 17);          // width
+
+    assert.deepEqual(imageDimensions(b), { width: 640, height: 480 });
+  });
+
+  it('reads WebP VP8X canvas size', () => {
+    const b = Buffer.alloc(32, 0);
+    b.write('RIFF', 0, 'ascii');
+    b.write('WEBP', 8, 'ascii');
+    b.write('VP8X', 12, 'ascii');
+    b.writeUIntLE(1023, 24, 3);        // stored as width - 1
+    b.writeUIntLE(767, 27, 3);
+
+    assert.deepEqual(imageDimensions(b), { width: 1024, height: 768 });
+  });
+
+  it('returns null for formats it cannot parse, rather than guessing', () => {
+    assert.equal(imageDimensions(Buffer.alloc(4)), null);
+    assert.equal(imageDimensions(Buffer.alloc(64, 7)), null);
+  });
+});
+
+describe('describeSizeMismatch', () => {
+  it('reports a pixel-size substitution', () => {
+    // The observed case: 1024x1536 requested, 1402x1122 returned.
+    const warning = describeSizeMismatch({
+      requestedSize: '1024x1536',
+      actual: { width: 1402, height: 1122 },
+    });
+
+    assert.match(warning, /Requested 1024x1536 but the provider returned 1402x1122/);
+  });
+
+  it('stays quiet when the size matches', () => {
+    assert.equal(
+      describeSizeMismatch({ requestedSize: '1536x1024', actual: { width: 1536, height: 1024 } }),
+      undefined,
+    );
+  });
+
+  it('reports an aspect-ratio substitution within a rounding tolerance', () => {
+    assert.equal(
+      describeSizeMismatch({ aspectRatio: '16:9', actual: { width: 1920, height: 1080 } }),
+      undefined,
+    );
+    assert.match(
+      describeSizeMismatch({ aspectRatio: '16:9', actual: { width: 1024, height: 1024 } }),
+      /Requested aspect ratio 16:9/,
+    );
+  });
+
+  it('says nothing when dimensions could not be read', () => {
+    assert.equal(describeSizeMismatch({ requestedSize: '1024x1024', actual: null }), undefined);
+  });
+});

package/skills/content/mermaid/LICENSE

@@ -0,0 +1,3 @@
+MIT License
+
+Copyright (c) 2026 1AboveIO