@1aboveio/skills 0.0.0-stage → 1.0.0

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

@@ -0,0 +1,212 @@
+import assert from 'node:assert/strict';
+import { mkdtemp, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { describe, it } from 'node:test';
+
+import {
+  DEFAULT_OPENAI_BASE_URL,
+  expandPiValue,
+  piModelsPath,
+  resolveGemini,
+  resolveOpenAI,
+} from './credentials.mjs';
+
+async function writeConfig(contents) {
+  const dir = await mkdtemp(join(tmpdir(), 'image-gen-creds-'));
+  const path = join(dir, 'models.json');
+  await writeFile(path, typeof contents === 'string' ? contents : JSON.stringify(contents));
+  return path;
+}
+
+const piConfig = (openai) => ({ providers: { openai } });
+
+// A literal key, the case where the pi fallback can actually produce one.
+const LITERAL = { baseUrl: 'https://pi-gateway.example/v1', apiKey: 'pi-key' };
+
+describe('expandPiValue', () => {
+  it('passes literals through', () => {
+    assert.equal(expandPiValue('sk-literal', {}).value, 'sk-literal');
+  });
+
+  it('expands $VAR and ${VAR}', () => {
+    assert.equal(expandPiValue('$KEY', { KEY: 'v' }).value, 'v');
+    assert.equal(expandPiValue('${KEY}', { KEY: 'v' }).value, 'v');
+  });
+
+  it('expands variables embedded in surrounding text', () => {
+    const resolved = expandPiValue('https://$HOST/v1', { HOST: 'gw.example' });
+
+    assert.equal(resolved.value, 'https://gw.example/v1');
+  });
+
+  it('reports every unresolved variable instead of expanding partially', () => {
+    const resolved = expandPiValue('$A-$B', { A: 'a' });
+
+    assert.equal(resolved.value, undefined);
+    assert.deepEqual(resolved.missing, ['B']);
+  });
+
+  it('treats an empty variable as unset, as pi does', () => {
+    assert.deepEqual(expandPiValue('$KEY', { KEY: '' }).missing, ['KEY']);
+  });
+
+  it('honors the $$ and $! escapes', () => {
+    assert.equal(expandPiValue('$$KEY', { KEY: 'v' }).value, '$KEY');
+    assert.equal(expandPiValue('$!cmd', {}).value, '!cmd');
+  });
+
+  it('keeps a dangling $ or unterminated ${ literal', () => {
+    assert.equal(expandPiValue('pre$', {}).value, 'pre$');
+    assert.equal(expandPiValue('${unterminated', {}).value, '${unterminated');
+    assert.equal(expandPiValue('$ {KEY}', {}).value, '$ {KEY}');
+  });
+
+  it('flags !command values rather than executing them', () => {
+    const resolved = expandPiValue('!security find-generic-password -w', {});
+
+    assert.equal(resolved.value, undefined);
+    assert.equal(resolved.command, 'security find-generic-password -w');
+  });
+});
+
+describe('resolveOpenAI', () => {
+  it('prefers the environment over the pi config', async () => {
+    const configPath = await writeConfig(piConfig(LITERAL));
+    const resolved = await resolveOpenAI({
+      env: { OPENAI_API_KEY: 'env-key', OPENAI_BASE_URL: 'https://env-gateway.example/v1' },
+      configPath,
+    });
+
+    assert.equal(resolved.ok, true);
+    assert.equal(resolved.apiKey, 'env-key');
+    assert.equal(resolved.baseUrl, 'https://env-gateway.example/v1');
+  });
+
+  it('defaults the base URL when only the env key is set', async () => {
+    const resolved = await resolveOpenAI({ env: { OPENAI_API_KEY: 'k' }, configPath: '/nope' });
+
+    assert.equal(resolved.baseUrl, DEFAULT_OPENAI_BASE_URL);
+  });
+
+  it('strips trailing slashes so the path join stays well formed', async () => {
+    const resolved = await resolveOpenAI({
+      env: { OPENAI_API_KEY: 'k', OPENAI_BASE_URL: 'https://gw.example/v1///' },
+      configPath: '/nope',
+    });
+
+    assert.equal(resolved.baseUrl, 'https://gw.example/v1');
+  });
+
+  it('falls back to a literal pi key, taking pi\'s base URL with it', async () => {
+    const configPath = await writeConfig(piConfig(LITERAL));
+    const resolved = await resolveOpenAI({ env: {}, configPath });
+
+    assert.equal(resolved.ok, true);
+    assert.equal(resolved.apiKey, 'pi-key');
+    assert.equal(resolved.baseUrl, 'https://pi-gateway.example/v1');
+    assert.match(resolved.source, /^pi config/);
+  });
+
+  it('expands a pi key that references another variable', async () => {
+    const configPath = await writeConfig(piConfig({ ...LITERAL, apiKey: '$GAPSEE_KEY' }));
+    const resolved = await resolveOpenAI({ env: { GAPSEE_KEY: 'sk-real' }, configPath });
+
+    assert.equal(resolved.ok, true);
+    assert.equal(resolved.apiKey, 'sk-real');
+  });
+
+  it('never sends an unexpanded template as the bearer token', async () => {
+    // The bug this guards: `$OPENAI_API_KEY` reaching the API verbatim.
+    const configPath = await writeConfig(piConfig({ ...LITERAL, apiKey: '$SOME_KEY' }));
+    const resolved = await resolveOpenAI({ env: {}, configPath });
+
+    assert.equal(resolved.ok, false);
+    assert.match(resolved.reason, /\$SOME_KEY/);
+  });
+
+  it('explains why a pi entry pointing at $OPENAI_API_KEY can never satisfy the fallback', async () => {
+    const configPath = await writeConfig(piConfig({ ...LITERAL, apiKey: '$OPENAI_API_KEY' }));
+    const resolved = await resolveOpenAI({ env: {}, configPath });
+
+    assert.equal(resolved.ok, false);
+    assert.match(resolved.reason, /can never satisfy this fallback/);
+  });
+
+  it('expands a templated pi base URL', async () => {
+    const configPath = await writeConfig(piConfig({ apiKey: 'pi-key', baseUrl: 'https://$GW/v1' }));
+    const resolved = await resolveOpenAI({ env: { GW: 'gw.example' }, configPath });
+
+    assert.equal(resolved.baseUrl, 'https://gw.example/v1');
+  });
+
+  it('fails rather than silently retargeting when the pi base URL cannot expand', async () => {
+    // Falling back to api.openai.com here would send a gateway key to OpenAI.
+    const configPath = await writeConfig(piConfig({ apiKey: 'pi-key', baseUrl: 'https://$GW/v1' }));
+    const resolved = await resolveOpenAI({ env: {}, configPath });
+
+    assert.equal(resolved.ok, false);
+    assert.match(resolved.reason, /\$GW/);
+  });
+
+  it('defaults the base URL when the pi provider omits one', async () => {
+    const configPath = await writeConfig(piConfig({ apiKey: 'pi-key' }));
+    const resolved = await resolveOpenAI({ env: {}, configPath });
+
+    assert.equal(resolved.baseUrl, DEFAULT_OPENAI_BASE_URL);
+  });
+
+  it('reports !command keys as unsupported instead of running them', async () => {
+    const configPath = await writeConfig(piConfig({ ...LITERAL, apiKey: '!echo sk-x' }));
+    const resolved = await resolveOpenAI({ env: {}, configPath });
+
+    assert.equal(resolved.ok, false);
+    assert.match(resolved.reason, /does not execute config commands/);
+  });
+
+  it('ignores OPENAI_BASE_URL when the key comes from pi', async () => {
+    const configPath = await writeConfig(piConfig(LITERAL));
+    const resolved = await resolveOpenAI({
+      env: { OPENAI_BASE_URL: 'https://env-gateway.example/v1' },
+      configPath,
+    });
+
+    assert.equal(resolved.baseUrl, 'https://pi-gateway.example/v1');
+  });
+
+  it('fails with the config path when there is nothing to fall back to', async () => {
+    const missing = await resolveOpenAI({ env: {}, configPath: '/definitely/not/here.json' });
+    const malformed = await resolveOpenAI({ env: {}, configPath: await writeConfig('{ not json') });
+    const noKey = await writeConfig(piConfig({ baseUrl: 'https://x.example/v1' }));
+    const otherProvider = await writeConfig({ providers: { deepseek: { apiKey: 'k' } } });
+
+    assert.equal(missing.ok, false);
+    assert.match(missing.reason, /definitely\/not\/here\.json/);
+    assert.equal(malformed.ok, false);
+    assert.equal((await resolveOpenAI({ env: {}, configPath: noKey })).ok, false);
+    assert.equal((await resolveOpenAI({ env: {}, configPath: otherProvider })).ok, false);
+  });
+});
+
+describe('piModelsPath', () => {
+  it('honors PI_CODING_AGENT_DIR', () => {
+    assert.equal(piModelsPath({ PI_CODING_AGENT_DIR: '/custom/agent' }), '/custom/agent/models.json');
+  });
+
+  it('defaults to the pi agent directory under $HOME', () => {
+    assert.match(piModelsPath({}), /[/\\]\.pi[/\\]agent[/\\]models\.json$/);
+  });
+});
+
+describe('resolveGemini', () => {
+  it('reads the env key', () => {
+    assert.equal(resolveGemini({ env: { GEMINI_API_KEY: 'g-key' } }).apiKey, 'g-key');
+  });
+
+  it('fails with a reason without one', () => {
+    const resolved = resolveGemini({ env: {} });
+
+    assert.equal(resolved.ok, false);
+    assert.match(resolved.reason, /GEMINI_API_KEY/);
+  });
+});

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

@@ -0,0 +1,240 @@
+#!/usr/bin/env node
+
+/**
+ * Image generation script supporting OpenAI gpt-image-2 and Google Gemini.
+ *
+ * OpenAI: OPENAI_API_KEY + optional OPENAI_BASE_URL, falling back to the pi
+ *         harness config. See scripts/credentials.mjs.
+ * Gemini: Requires GEMINI_API_KEY.
+ */
+
+import { writeFile, mkdir } from 'node:fs/promises';
+import { dirname, resolve } from 'node:path';
+
+import { resolveGemini, resolveOpenAI } from './credentials.mjs';
+import {
+  GEMINI_ASPECT_RATIOS,
+  OPENAI_SIZES,
+  QUALITIES,
+  describeSizeMismatch,
+  geminiAspectRatio,
+  imageDimensions,
+  openAiSize,
+  parseArgs,
+  resolveOutputPath,
+} from './options.mjs';
+
+// Image generation is slow — tens of seconds is normal — but an unbounded fetch
+// hangs forever on a stalled gateway with nothing on screen to explain why.
+const REQUEST_TIMEOUT_MS = 180_000;
+
+function usage() {
+  console.error('Usage: node generate.mjs "prompt" [options]');
+  console.error('');
+  console.error('Options:');
+  console.error('  --provider <openai|gemini>   Image provider (default: openai)');
+  console.error('  --model <model>              Model name (provider-specific)');
+  console.error(`  --size <size>                OpenAI: ${OPENAI_SIZES.join(', ')}`);
+  console.error('                               Gemini: WxH or an aspect ratio');
+  console.error(`                               (${GEMINI_ASPECT_RATIOS.join(', ')})`);
+  console.error(`  --quality <quality>          OpenAI only: ${QUALITIES.join(', ')}`);
+  console.error('  --output <path>              Output file path');
+}
+
+const { prompt, flags, errors, warnings } = parseArgs(process.argv.slice(2));
+
+for (const warning of warnings) console.warn(`Note: ${warning}`);
+
+if (errors.length) {
+  for (const error of errors) console.error(`Error: ${error}`);
+  process.exit(1);
+}
+
+if (!prompt) {
+  usage();
+  process.exit(1);
+}
+
+const provider = flags.provider || 'openai';
+const defaultOutputBase = `./generated-${Date.now()}`;
+
+async function postJson(url, { headers = {}, body }) {
+  try {
+    return await fetch(url, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json', ...headers },
+      body: JSON.stringify(body),
+      signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+    });
+  } catch (err) {
+    if (err.name === 'TimeoutError' || err.name === 'AbortError') {
+      console.error(`Error: no response within ${REQUEST_TIMEOUT_MS / 1000}s — the endpoint may be unreachable or overloaded.`);
+      process.exit(1);
+    }
+    throw err;
+  }
+}
+
+async function failOnBadResponse(response) {
+  if (response.ok) return;
+  console.error(`API Error (${response.status}): ${await response.text()}`);
+  process.exit(1);
+}
+
+// ─── OpenAI provider ───
+
+async function generateOpenAI() {
+  const credentials = await resolveOpenAI();
+  if (!credentials.ok) {
+    console.error(`Error: no usable OpenAI credentials. ${credentials.reason}`);
+    process.exit(1);
+  }
+
+  const { apiKey, baseUrl, source } = credentials;
+  const model = flags.model || 'gpt-image-2';
+  const quality = flags.quality || 'auto';
+
+  const size = openAiSize(flags.size);
+  if (size.error) {
+    console.error(`Error: ${size.error}`);
+    process.exit(1);
+  }
+
+  console.log(`Generating image with ${model}...`);
+  console.log(`Provider: OpenAI`);
+  console.log(`Endpoint: ${baseUrl} (credentials from ${source})`);
+  console.log(`Prompt: "${prompt}"`);
+  console.log(`Size: ${size.value}, Quality: ${quality}`);
+
+  const response = await postJson(`${baseUrl}/images/generations`, {
+    headers: { Authorization: `Bearer ${apiKey}` },
+    body: { model, prompt, n: 1, size: size.value, quality },
+  });
+  await failOnBadResponse(response);
+
+  const data = await response.json();
+  const imageData = data?.data?.[0];
+  if (!imageData) {
+    console.error('Error: no image data in response');
+    console.error(JSON.stringify(data, null, 2));
+    process.exit(1);
+  }
+
+  let buffer;
+  let mimeType = 'image/png';
+
+  if (imageData.b64_json) {
+    buffer = Buffer.from(imageData.b64_json, 'base64');
+    if (imageData.output_format) mimeType = `image/${imageData.output_format}`;
+  } else if (imageData.url) {
+    console.log('Downloading from URL...');
+    const download = await fetch(imageData.url, { signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS) });
+    if (!download.ok) {
+      console.error(`Failed to download image: ${download.status}`);
+      process.exit(1);
+    }
+    mimeType = download.headers.get('content-type') || mimeType;
+    buffer = Buffer.from(await download.arrayBuffer());
+  } else {
+    console.error('Error: response contains neither b64_json nor url');
+    process.exit(1);
+  }
+
+  await saveImage(buffer, mimeType, { requestedSize: flags.size });
+
+  if (imageData.revised_prompt) {
+    console.log(`\n📝 Revised prompt: ${imageData.revised_prompt}`);
+  }
+}
+
+// ─── Gemini provider ───
+
+async function generateGemini() {
+  const credentials = resolveGemini();
+  if (!credentials.ok) {
+    console.error(`Error: ${credentials.reason}`);
+    process.exit(1);
+  }
+
+  const model = flags.model || 'gemini-3-pro-image-preview';
+
+  // Gemini takes a ratio, not pixel dimensions, so a WxH --size is snapped to the
+  // nearest supported ratio. It used to be accepted and discarded entirely.
+  const aspect = geminiAspectRatio(flags.size);
+  if (aspect.error) {
+    console.error(`Error: ${aspect.error}`);
+    process.exit(1);
+  }
+
+  console.log(`Generating image with ${model}...`);
+  console.log(`Provider: Gemini (Nano Banana)`);
+  console.log(`Prompt: "${prompt}"`);
+  if (aspect.value) {
+    const from = aspect.snappedFrom ? ` (nearest ratio to ${aspect.snappedFrom})` : '';
+    console.log(`Aspect ratio: ${aspect.value}${from}`);
+  }
+
+  const generationConfig = { responseModalities: ['IMAGE', 'TEXT'] };
+  if (aspect.value) generationConfig.imageConfig = { aspectRatio: aspect.value };
+
+  const response = await postJson(
+    `https://generativelanguage.googleapis.com/v1beta/models/${model}:generateContent?key=${credentials.apiKey}`,
+    { body: { contents: [{ parts: [{ text: prompt }] }], generationConfig } },
+  );
+  await failOnBadResponse(response);
+
+  const data = await response.json();
+  const parts = data?.candidates?.[0]?.content?.parts;
+  if (!parts) {
+    console.error('Error: no content in response');
+    console.error(JSON.stringify(data, null, 2));
+    process.exit(1);
+  }
+
+  const imagePart = parts.find((part) => part.inlineData?.mimeType?.startsWith('image/'));
+  if (!imagePart) {
+    console.error('Error: no image found in response parts');
+    console.error('Available parts:', parts.map((part) => Object.keys(part)).join(', '));
+    process.exit(1);
+  }
+
+  await saveImage(Buffer.from(imagePart.inlineData.data, 'base64'), imagePart.inlineData.mimeType, {
+    aspectRatio: aspect.value,
+  });
+
+  const textPart = parts.find((part) => part.text);
+  if (textPart) console.log(`\n📝 Model response: ${textPart.text}`);
+}
+
+// ─── Helpers ───
+
+async function saveImage(buffer, mimeType, expected = {}) {
+  const { path, warning } = resolveOutputPath({
+    requested: flags.output,
+    defaultBase: defaultOutputBase,
+    mimeType,
+  });
+  const outputPath = resolve(path);
+
+  await mkdir(dirname(outputPath), { recursive: true });
+  await writeFile(outputPath, buffer);
+
+  if (warning) console.warn(`Note: ${warning}`);
+  console.log(`\n✅ Image saved to: ${outputPath}`);
+
+  const actual = imageDimensions(buffer);
+  const dimensions = actual ? `${actual.width}x${actual.height}, ` : '';
+  console.log(`   ${dimensions}${(buffer.length / 1024).toFixed(1)} KB`);
+
+  const mismatch = describeSizeMismatch({ ...expected, actual });
+  if (mismatch) console.warn(`Note: ${mismatch} Proxies and models do not always honor the requested size.`);
+}
+
+// ─── Main ───
+
+const generators = { openai: generateOpenAI, gemini: generateGemini };
+
+generators[provider]().catch((err) => {
+  console.error('Generation failed:', err.message);
+  process.exit(1);
+});