bananahub 0.1.0

package/lib/commands/validate-cmd.js

@@ -0,0 +1,42 @@
+import { resolve } from 'node:path';
+import { validateTemplate } from '../validate.js';
+import { bold, green, red, yellow, dim } from '../color.js';
+
+export async function validateCommand(args) {
+  const targetPath = args[0] ? resolve(args[0]) : process.cwd();
+
+  console.log(dim(`\n  Validating: ${targetPath}\n`));
+
+  const result = await validateTemplate(targetPath);
+
+  if (result.errors.length > 0) {
+    console.log(red(bold('  ERRORS:')));
+    for (const e of result.errors) {
+      console.log(red(`    - ${e}`));
+    }
+    console.log();
+  }
+
+  if (result.warnings.length > 0) {
+    console.log(yellow(bold('  WARNINGS:')));
+    for (const w of result.warnings) {
+      console.log(yellow(`    - ${w}`));
+    }
+    console.log();
+  }
+
+  if (result.meta) {
+    console.log(dim(`  ID: ${result.meta.id || '(not set)'}`));
+    console.log(dim(`  Type: ${result.meta.type || 'prompt'}`));
+    console.log(dim(`  Title: ${result.meta.title || '(not set)'}`));
+    console.log(dim(`  Profile: ${result.meta.profile || '(not set)'}`));
+  }
+
+  if (result.valid) {
+    console.log(green(bold('\n  VALID')));
+  } else {
+    console.log(red(bold('\n  INVALID')));
+    process.exitCode = 1;
+  }
+  console.log();
+}

package/lib/constants.js

@@ -0,0 +1,19 @@
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+export const CLI_VERSION = '0.1.0';
+export const TEMPLATES_DIR = join(homedir(), '.config', 'nanobanana', 'templates');
+export const REGISTRY_FILE = '.registry.json';
+export const SOURCE_FILE = '.source.json';
+export const GITHUB_API = 'https://api.github.com';
+export const HUB_API = 'https://bananahub-api.zhan9kun.workers.dev/api';
+export const HUB_SITE = 'https://nano-banana-hub.github.io';
+export const HUB_CATALOG_URL = `${HUB_SITE}/catalog.json`;
+
+export const VALID_PROFILES = [
+  'photo', 'illustration', 'diagram', 'text-heavy',
+  'minimal', 'sticker', '3d', 'product', 'concept-art', 'general'
+];
+
+export const VALID_DIFFICULTIES = ['beginner', 'intermediate', 'advanced'];
+export const VALID_TEMPLATE_TYPES = ['prompt', 'workflow'];

package/lib/frontmatter.js

@@ -0,0 +1,130 @@
+/**
+ * Minimal YAML frontmatter parser.
+ * Handles the subset used by template.md files (scalars, arrays, objects-in-arrays).
+ */
+
+export function parseFrontmatter(text) {
+  const match = text.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+  if (!match) return null;
+  const yaml = match[1];
+  return parseYaml(yaml);
+}
+
+function parseYaml(text) {
+  const result = {};
+  const lines = text.split(/\r?\n/);
+  let i = 0;
+
+  while (i < lines.length) {
+    const line = lines[i];
+
+    // Skip blank lines and comments
+    if (!line.trim() || line.trim().startsWith('#')) {
+      i++;
+      continue;
+    }
+
+    const keyMatch = line.match(/^(\w[\w_]*):\s*(.*)/);
+    if (!keyMatch) { i++; continue; }
+
+    const key = keyMatch[1];
+    let value = keyMatch[2].trim();
+
+    // Inline array: [a, b, c]
+    if (value.startsWith('[')) {
+      result[key] = parseInlineArray(value);
+      i++;
+      continue;
+    }
+
+    // Quoted string
+    if ((value.startsWith('"') && value.endsWith('"')) ||
+        (value.startsWith("'") && value.endsWith("'"))) {
+      result[key] = value.slice(1, -1);
+      i++;
+      continue;
+    }
+
+    // Empty value — check for block array/object below
+    if (value === '') {
+      // Look ahead for block array (lines starting with "  - ")
+      const items = [];
+      let j = i + 1;
+      while (j < lines.length && lines[j].match(/^  - /)) {
+        const itemLine = lines[j].replace(/^  - /, '').trim();
+        // Check if this array item has sub-keys
+        let k = j + 1;
+        const subKeys = {};
+        let hasSubKeys = false;
+        while (k < lines.length && lines[k].match(/^    \w/)) {
+          const subMatch = lines[k].match(/^    (\w[\w_]*):\s*(.*)/);
+          if (subMatch) {
+            hasSubKeys = true;
+            let sv = subMatch[2].trim();
+            if ((sv.startsWith('"') && sv.endsWith('"')) ||
+                (sv.startsWith("'") && sv.endsWith("'"))) {
+              sv = sv.slice(1, -1);
+            }
+            subKeys[subMatch[1]] = coerce(sv);
+          }
+          k++;
+        }
+
+        if (hasSubKeys) {
+          // First line of block item may have a key: value too
+          const firstKeyMatch = itemLine.match(/^(\w[\w_]*):\s*(.*)/);
+          if (firstKeyMatch) {
+            let fv = firstKeyMatch[2].trim();
+            if ((fv.startsWith('"') && fv.endsWith('"')) ||
+                (fv.startsWith("'") && fv.endsWith("'"))) {
+              fv = fv.slice(1, -1);
+            }
+            subKeys[firstKeyMatch[1]] = coerce(fv);
+          }
+          items.push(subKeys);
+          j = k;
+        } else {
+          items.push(coerce(itemLine));
+          j++;
+        }
+      }
+
+      if (items.length > 0) {
+        result[key] = items;
+        i = j;
+        continue;
+      }
+
+      result[key] = '';
+      i++;
+      continue;
+    }
+
+    // Plain scalar
+    result[key] = coerce(value);
+    i++;
+  }
+
+  return result;
+}
+
+function parseInlineArray(str) {
+  const inner = str.slice(1, -1);
+  return inner.split(',').map(s => {
+    s = s.trim();
+    if ((s.startsWith('"') && s.endsWith('"')) ||
+        (s.startsWith("'") && s.endsWith("'"))) {
+      return s.slice(1, -1);
+    }
+    return s;
+  }).filter(Boolean);
+}
+
+function coerce(val) {
+  if (val === 'true') return true;
+  if (val === 'false') return false;
+  if (val === 'null' || val === '~') return null;
+  if (/^\d+$/.test(val)) return parseInt(val, 10);
+  if (/^\d+\.\d+$/.test(val)) return parseFloat(val);
+  return val;
+}

package/lib/github.js

@@ -0,0 +1,79 @@
+import { GITHUB_API } from './constants.js';
+
+/**
+ * Fetch repo info from GitHub API.
+ */
+export async function getRepoInfo(repo) {
+  const res = await fetch(`${GITHUB_API}/repos/${repo}`, {
+    headers: ghHeaders()
+  });
+  if (!res.ok) {
+    if (res.status === 404) throw new Error(`Repository not found: ${repo}`);
+    throw new Error(`GitHub API error: ${res.status} ${res.statusText}`);
+  }
+  return res.json();
+}
+
+/**
+ * Check if a file exists at the repo root.
+ */
+export async function getFileContent(repo, path, ref = 'HEAD') {
+  const res = await fetch(`${GITHUB_API}/repos/${repo}/contents/${path}`, {
+    headers: ghHeaders()
+  });
+  if (!res.ok) return null;
+  const data = await res.json();
+  if (data.encoding === 'base64' && data.content) {
+    return Buffer.from(data.content, 'base64').toString('utf8');
+  }
+  return null;
+}
+
+/**
+ * Get the default branch and latest commit SHA.
+ */
+export async function getDefaultBranchInfo(repo) {
+  const info = await getRepoInfo(repo);
+  return {
+    branch: info.default_branch,
+    fullName: info.full_name
+  };
+}
+
+/**
+ * Download repo tarball and return the buffer.
+ */
+export async function downloadTarball(repo, ref = 'HEAD') {
+  const url = `${GITHUB_API}/repos/${repo}/tarball/${ref}`;
+  const res = await fetch(url, {
+    headers: ghHeaders(),
+    redirect: 'follow'
+  });
+  if (!res.ok) {
+    throw new Error(`Failed to download tarball: ${res.status} ${res.statusText}`);
+  }
+  return Buffer.from(await res.arrayBuffer());
+}
+
+/**
+ * Get latest commit SHA for a ref.
+ */
+export async function getLatestSha(repo, ref = 'HEAD') {
+  const res = await fetch(`${GITHUB_API}/repos/${repo}/commits/${ref}`, {
+    headers: ghHeaders()
+  });
+  if (!res.ok) return null;
+  const data = await res.json();
+  return data.sha;
+}
+
+function ghHeaders() {
+  const headers = {
+    'Accept': 'application/vnd.github.v3+json',
+    'User-Agent': 'bananahub-cli/0.1.0'
+  };
+  if (process.env.GITHUB_TOKEN) {
+    headers['Authorization'] = `token ${process.env.GITHUB_TOKEN}`;
+  }
+  return headers;
+}

package/lib/hub.js

@@ -0,0 +1,103 @@
+import { CLI_VERSION, HUB_API, HUB_CATALOG_URL } from './constants.js';
+
+export async function fetchHubCatalog() {
+  const res = await fetch(HUB_CATALOG_URL, {
+    headers: hubHeaders()
+  });
+
+  if (!res.ok) {
+    throw new Error(`Failed to fetch hub catalog: ${res.status} ${res.statusText}`);
+  }
+
+  const data = await res.json();
+  if (!data || !Array.isArray(data.templates)) {
+    throw new Error('Hub catalog is missing the templates array.');
+  }
+
+  return data;
+}
+
+export async function fetchHubTrending({ period = '7d', limit = 10 } = {}) {
+  const url = new URL(`${HUB_API}/trending`);
+  url.searchParams.set('period', period);
+  url.searchParams.set('limit', String(limit));
+
+  const res = await fetch(url, {
+    headers: hubHeaders()
+  });
+
+  if (!res.ok) {
+    throw new Error(`Failed to fetch hub trending data: ${res.status} ${res.statusText}`);
+  }
+
+  const data = await res.json();
+  if (!data || !Array.isArray(data.templates)) {
+    throw new Error('Hub trending response is missing the templates array.');
+  }
+
+  return data;
+}
+
+export function buildCatalogLookup(catalog) {
+  const lookup = new Map();
+  for (const template of catalog.templates || []) {
+    lookup.set(templateKey(template.repo, template.id), template);
+  }
+  return lookup;
+}
+
+export function compareCatalogPriority(left, right) {
+  const pinnedDiff = getPinnedRank(left) - getPinnedRank(right);
+  if (pinnedDiff !== 0) {
+    return pinnedDiff;
+  }
+
+  const featuredDiff = toFlag(right?.featured) - toFlag(left?.featured);
+  if (featuredDiff !== 0) {
+    return featuredDiff;
+  }
+
+  const sourceDiff = sourceRank(right?.catalog_source) - sourceRank(left?.catalog_source);
+  if (sourceDiff !== 0) {
+    return sourceDiff;
+  }
+
+  const officialDiff = toFlag(right?.official) - toFlag(left?.official);
+  if (officialDiff !== 0) {
+    return officialDiff;
+  }
+
+  const updatedDiff = String(right?.updated || '').localeCompare(String(left?.updated || ''));
+  if (updatedDiff !== 0) {
+    return updatedDiff;
+  }
+
+  return String(left?.id || '').localeCompare(String(right?.id || ''));
+}
+
+export function templateKey(repo, templateId) {
+  return `${repo || ''}::${templateId || ''}`;
+}
+
+function hubHeaders() {
+  return {
+    Accept: 'application/json',
+    'User-Agent': `bananahub-cli/${CLI_VERSION}`
+  };
+}
+
+function getPinnedRank(template) {
+  return Number.isFinite(template?.pinned_rank)
+    ? template.pinned_rank
+    : Number.POSITIVE_INFINITY;
+}
+
+function toFlag(value) {
+  return value ? 1 : 0;
+}
+
+function sourceRank(source) {
+  if (source === 'curated') return 2;
+  if (source === 'discovered') return 1;
+  return 0;
+}

package/lib/registry.js

@@ -0,0 +1,68 @@
+import { readdir, readFile, writeFile, mkdir } from 'node:fs/promises';
+import { join } from 'node:path';
+import { TEMPLATES_DIR, REGISTRY_FILE } from './constants.js';
+import { parseFrontmatter } from './frontmatter.js';
+
+/**
+ * Rebuild .registry.json by scanning all installed template directories.
+ */
+export async function rebuildRegistry() {
+  await mkdir(TEMPLATES_DIR, { recursive: true });
+  const entries = await readdir(TEMPLATES_DIR, { withFileTypes: true });
+  const templates = [];
+
+  for (const entry of entries) {
+    if (!entry.isDirectory() || entry.name.startsWith('.')) continue;
+    const tmplPath = join(TEMPLATES_DIR, entry.name, 'template.md');
+    try {
+      const content = await readFile(tmplPath, 'utf8');
+      const fm = parseFrontmatter(content);
+      if (!fm) continue;
+
+      let source = null;
+      try {
+        const srcJson = await readFile(join(TEMPLATES_DIR, entry.name, '.source.json'), 'utf8');
+        source = JSON.parse(srcJson);
+      } catch { /* no source info */ }
+
+      templates.push({
+        id: fm.id || entry.name,
+        type: fm.type || 'prompt',
+        title: fm.title || '',
+        title_en: fm.title_en || '',
+        author: fm.author || '',
+        profile: fm.profile || 'general',
+        tags: fm.tags || [],
+        difficulty: fm.difficulty || 'beginner',
+        aspect: fm.aspect || '',
+        models: Array.isArray(fm.models) ? fm.models.map(m => m.name || m) : [],
+        source: source?.repo || '',
+        version: fm.version || '0.0.0',
+        installed_at: source?.installed_at || ''
+      });
+    } catch {
+      // skip unreadable templates
+    }
+  }
+
+  const registry = {
+    version: '1.0.0',
+    generated_at: new Date().toISOString(),
+    templates
+  };
+
+  await writeFile(join(TEMPLATES_DIR, REGISTRY_FILE), JSON.stringify(registry, null, 2));
+  return registry;
+}
+
+/**
+ * Load the current registry (or rebuild if missing).
+ */
+export async function loadRegistry() {
+  try {
+    const raw = await readFile(join(TEMPLATES_DIR, REGISTRY_FILE), 'utf8');
+    return JSON.parse(raw);
+  } catch {
+    return rebuildRegistry();
+  }
+}

package/lib/validate.js

@@ -0,0 +1,236 @@
+import { readFile, access, readdir } from 'node:fs/promises';
+import { join } from 'node:path';
+import { parseFrontmatter } from './frontmatter.js';
+import { VALID_PROFILES, VALID_DIFFICULTIES, VALID_TEMPLATE_TYPES } from './constants.js';
+
+const SAMPLE_FILE_PATTERN = /^sample-[a-z0-9.]+(?:-[a-z0-9.]+)*-\d{2}\.(jpg|jpeg|png|webp)$/i;
+const DEFAULT_TEMPLATE_TYPE = 'prompt';
+
+/**
+ * Validate a template directory. Returns { valid, errors, warnings, meta }.
+ */
+export async function validateTemplate(dirPath) {
+  const errors = [];
+  const warnings = [];
+  let meta = null;
+
+  const tmplPath = join(dirPath, 'template.md');
+  let content;
+  try {
+    content = await readFile(tmplPath, 'utf8');
+  } catch {
+    return { valid: false, errors: ['template.md not found'], warnings, meta };
+  }
+
+  const fm = parseFrontmatter(content);
+  if (!fm) {
+    return { valid: false, errors: ['No YAML frontmatter found (missing --- delimiters)'], warnings, meta };
+  }
+
+  const templateType = fm.type || DEFAULT_TEMPLATE_TYPE;
+  meta = { ...fm, type: templateType };
+
+  const requiredFields = ['title', 'profile'];
+  for (const field of requiredFields) {
+    if (!fm[field]) {
+      errors.push(`Missing required field: ${field}`);
+    }
+  }
+
+  if (fm.type && !VALID_TEMPLATE_TYPES.includes(fm.type)) {
+    errors.push(`Invalid type "${fm.type}". Must be one of: ${VALID_TEMPLATE_TYPES.join(', ')}`);
+  } else if (!fm.type) {
+    warnings.push('No type defined — defaulting to `prompt`. Add `type: prompt` or `type: workflow` for clarity');
+  }
+
+  if (fm.id && !/^[a-z][a-z0-9-]{1,48}[a-z0-9]$/.test(fm.id)) {
+    warnings.push(`ID "${fm.id}" should be lowercase, hyphens only, 3-50 chars`);
+  }
+
+  if (fm.profile && !VALID_PROFILES.includes(fm.profile)) {
+    errors.push(`Invalid profile "${fm.profile}". Must be one of: ${VALID_PROFILES.join(', ')}`);
+  }
+
+  if (fm.difficulty && !VALID_DIFFICULTIES.includes(fm.difficulty)) {
+    warnings.push(`Invalid difficulty "${fm.difficulty}". Should be: ${VALID_DIFFICULTIES.join(', ')}`);
+  }
+
+  if (!fm.tags || !Array.isArray(fm.tags) || fm.tags.length === 0) {
+    warnings.push('No tags defined — templates are harder to discover without tags');
+  } else if (fm.tags.length < 3) {
+    warnings.push(`Only ${fm.tags.length} tags — recommend at least 3 for better discoverability`);
+  }
+
+  if (fm.version && !/^\d+\.\d+\.\d+/.test(fm.version)) {
+    warnings.push(`Version "${fm.version}" is not valid semver`);
+  }
+
+  if (!fm.models || !Array.isArray(fm.models) || fm.models.length === 0) {
+    warnings.push('No models listed — users won\'t know which models are tested');
+  }
+
+  validateBody(content, templateType, warnings);
+  await validateSamplesDir(dirPath, templateType, warnings);
+  await validateSampleMetadata(dirPath, meta, warnings);
+  await validateReadme(dirPath, meta, warnings);
+
+  return {
+    valid: errors.length === 0,
+    errors,
+    warnings,
+    meta
+  };
+}
+
+function validateBody(content, templateType, warnings) {
+  if (templateType === 'workflow') {
+    const requiredSections = ['## Goal', '## Inputs', '## Steps', '## Prompt Blocks'];
+    for (const section of requiredSections) {
+      if (!content.includes(section)) {
+        warnings.push(`Workflow template should include a "${section}" section`);
+      }
+    }
+    if (!/^\d+\.\s+/m.test(content)) {
+      warnings.push('Workflow template should include a numbered step list under "## Steps"');
+    }
+    return;
+  }
+
+  if (!content.includes('## Prompt Template') && !content.includes('## prompt template')) {
+    warnings.push('No "## Prompt Template" section found');
+  }
+
+  const varMatches = content.match(/\{\{(\w+)(?:\|[^}]*)?\}\}/g);
+  if (!varMatches || varMatches.length === 0) {
+    warnings.push('No template variables ({{var|default}}) found — template is static');
+  }
+}
+
+async function validateSamplesDir(dirPath, templateType, warnings) {
+  try {
+    const samplesDir = join(dirPath, 'samples');
+    await access(samplesDir);
+    const sampleFiles = await readdir(samplesDir);
+    const imageFiles = sampleFiles.filter(f => /\.(jpg|jpeg|png|webp)$/i.test(f));
+    if (imageFiles.length === 0 && templateType === 'prompt') {
+      warnings.push('samples/ directory exists but contains no images');
+    }
+  } catch {
+    if (templateType === 'prompt') {
+      warnings.push('No samples/ directory — sample images help users preview results');
+    }
+  }
+}
+
+async function validateSampleMetadata(dirPath, fm, warnings) {
+  if (!fm.samples || !Array.isArray(fm.samples) || fm.samples.length === 0) {
+    if (fm.type === 'prompt') {
+      warnings.push('No sample metadata in frontmatter — add `samples` entries with file/model/prompt/aspect');
+    }
+    return;
+  }
+
+  for (const sample of fm.samples) {
+    if (!sample || typeof sample !== 'object') {
+      warnings.push('Invalid sample metadata entry — each `samples` item should be an object');
+      continue;
+    }
+
+    if (!sample.file) {
+      warnings.push('A sample entry is missing `file`');
+      continue;
+    }
+
+    const fileName = sample.file.split('/').pop();
+    if (!SAMPLE_FILE_PATTERN.test(fileName)) {
+      warnings.push(`Sample file "${sample.file}" should follow sample-{model-short}-{nn}.ext naming`);
+    }
+
+    if (!sample.model) {
+      warnings.push(`Sample "${sample.file}" is missing \`model\``);
+    } else if (!fileNameIncludesModel(fileName, sample.model)) {
+      warnings.push(`Sample file "${sample.file}" should include the generating model shorthand for "${sample.model}"`);
+    }
+
+    if (!sample.prompt) {
+      warnings.push(`Sample "${sample.file}" is missing \`prompt\``);
+    }
+
+    if (!sample.aspect) {
+      warnings.push(`Sample "${sample.file}" is missing \`aspect\``);
+    }
+
+    try {
+      await access(join(dirPath, sample.file));
+    } catch {
+      warnings.push(`Sample file not found on disk: ${sample.file}`);
+    }
+  }
+}
+
+async function validateReadme(dirPath, fm, warnings) {
+  let readme;
+  try {
+    readme = await readFile(join(dirPath, 'README.md'), 'utf8');
+  } catch {
+    warnings.push('No README.md — published templates should document install, verified models, supported models, and sample mappings');
+    return;
+  }
+
+  if (!hasSection(readme, ['Verified Models', '验证模型', '已验证模型'])) {
+    warnings.push('README.md should include a "Verified Models" section');
+  }
+
+  if (!hasSection(readme, ['Supported Models', '支持模型', '兼容模型'])) {
+    warnings.push('README.md should include a "Supported Models" section');
+  }
+
+  if (!hasSection(readme, ['Sample Outputs', 'Sample Output', 'Samples', '样图', '示例输出'])) {
+    warnings.push('README.md should include a sample mapping section that ties image files to models and prompts');
+  }
+
+  if (Array.isArray(fm.samples)) {
+    for (const sample of fm.samples) {
+      if (!sample || typeof sample !== 'object' || !sample.file) {
+        continue;
+      }
+
+      const fileName = sample.file.split('/').pop();
+      if (!readme.includes(fileName)) {
+        warnings.push(`README.md should reference sample file "${fileName}" in its sample mapping`);
+      }
+
+      if (sample.model && !readme.includes(sample.model)) {
+        warnings.push(`README.md should mention sample model "${sample.model}"`);
+      }
+    }
+  }
+}
+
+function hasSection(content, names) {
+  return names.some((name) => {
+    const pattern = new RegExp(`^##\\s+${escapeRegExp(name)}\\s*$`, 'im');
+    return pattern.test(content);
+  });
+}
+
+function fileNameIncludesModel(fileName, modelName) {
+  const normalizedFileName = String(fileName || '').toLowerCase();
+  const normalizedModel = String(modelName || '').toLowerCase();
+  const versionTierMatch = normalizedModel.match(/gemini-(\d+(?:\.\d+)?)-(pro|flash)/);
+
+  if (normalizedFileName.includes(normalizedModel)) {
+    return true;
+  }
+
+  if (versionTierMatch) {
+    const shorthand = `${versionTierMatch[1]}-${versionTierMatch[2]}`;
+    return normalizedFileName.includes(shorthand);
+  }
+
+  return false;
+}
+
+function escapeRegExp(value) {
+  return String(value).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}