json-humanized 2.0.0

package/src/parsers/index.js

@@ -0,0 +1,119 @@
+'use strict';
+
+/**
+ * parsers/index.js — unified parser for JSON, YAML, and TOML.
+ *
+ * JSON is always available (built-in).
+ * YAML requires: npm install js-yaml
+ * TOML requires: npm install @iarna/toml
+ *
+ * If a peer dependency is missing, a clear error is thrown with install hint.
+ */
+
+const path = require('path');
+
+// ─── helpers ─────────────────────────────────────────────────────────────────
+
+function requireOptional(pkg, installHint) {
+  try {
+    return require(pkg);
+  } catch {
+    throw new Error(
+      `Optional dependency "${pkg}" is required to parse this file.\n` +
+      `Install it with: npm install ${installHint || pkg}`
+    );
+  }
+}
+
+function detectFormatFromExt(filePath) {
+  const ext = path.extname(filePath).toLowerCase();
+  if (ext === '.json') return 'json';
+  if (ext === '.yaml' || ext === '.yml') return 'yaml';
+  if (ext === '.toml') return 'toml';
+  return null;
+}
+
+function detectFormatFromContent(text) {
+  const trimmed = text.trimStart();
+  // TOML starts with [section] or key = value
+  if (/^\[[\w.]+\]/.test(trimmed) || /^\w[\w.-]*\s*=/.test(trimmed)) return 'toml';
+  // JSON starts with { or [
+  if (trimmed.startsWith('{') || trimmed.startsWith('[')) return 'json';
+  // Fallback: try YAML (it's a superset of JSON anyway)
+  return 'yaml';
+}
+
+// ─── parsers ─────────────────────────────────────────────────────────────────
+
+function parseJSON(text) {
+  try {
+    return JSON.parse(text);
+  } catch (err) {
+    throw new Error(`Invalid JSON: ${err.message}`);
+  }
+}
+
+function parseYAML(text) {
+  const yaml = requireOptional('js-yaml', 'js-yaml');
+  try {
+    return yaml.load(text);
+  } catch (err) {
+    throw new Error(`Invalid YAML: ${err.message}`);
+  }
+}
+
+function parseTOML(text) {
+  const toml = requireOptional('@iarna/toml', '@iarna/toml');
+  try {
+    return toml.parse(text);
+  } catch (err) {
+    throw new Error(`Invalid TOML: ${err.message}`);
+  }
+}
+
+// ─── public API ──────────────────────────────────────────────────────────────
+
+/**
+ * Parse text in JSON, YAML, or TOML format.
+ *
+ * @param {string} text       raw file contents
+ * @param {string} [filePath] optional path hint for format detection
+ * @param {string} [format]   explicit format override: 'json'|'yaml'|'toml'
+ * @returns {*}               parsed JavaScript value
+ */
+function parseAny(text, filePath, format) {
+  const fmt =
+    format ||
+    (filePath ? detectFormatFromExt(filePath) : null) ||
+    detectFormatFromContent(text);
+
+  switch (fmt) {
+    case 'json': return parseJSON(text);
+    case 'yaml': return parseYAML(text);
+    case 'toml': return parseTOML(text);
+    default:
+      // Last resort: try JSON, then YAML
+      try { return parseJSON(text); } catch {}
+      return parseYAML(text);
+  }
+}
+
+/**
+ * Read and parse a file from disk.
+ *
+ * @param {string} filePath
+ * @param {string} [formatOverride]
+ * @returns {*}
+ */
+function parseFile(filePath, formatOverride) {
+  const fs   = require('fs');
+  const text = fs.readFileSync(filePath, 'utf8');
+  return parseAny(text, filePath, formatOverride);
+}
+
+/**
+ * List supported extensions.
+ */
+const SUPPORTED_EXTENSIONS = ['.json', '.yaml', '.yml', '.toml'];
+
+module.exports = { parseAny, parseFile, SUPPORTED_EXTENSIONS };

package/src/strategies/ai.js

@@ -0,0 +1,108 @@
+'use strict';
+
+// ─────────────────────────────────────────────────────────────────────────────
+//  json-humanized · AI Strategy router
+//  Supports: anthropic (default), openai, ollama
+// ─────────────────────────────────────────────────────────────────────────────
+
+const SYSTEM_PROMPT = `You are a JSON data interpreter. Your job is to transform raw JSON into clear, natural, human-readable prose that anyone can understand — even without technical knowledge.
+
+Rules:
+1. Write in plain English. No jargon, no code, no JSON syntax in your output.
+2. Describe what the data MEANS, not just what it contains.
+3. Use a warm, professional tone.
+4. Identify patterns: if it's a list of users, say "This is a list of 5 users…"
+5. Highlight important or unusual values.
+6. Group related fields logically in your description.
+7. If a field looks sensitive (password, token, secret), say it's hidden — don't echo it.
+8. Keep it concise but complete. Aim for 3–10 sentences for simple objects, more for complex ones.
+9. Never use bullet points or markdown — write flowing paragraphs.
+10. If there's a list, summarize the pattern and give 1–2 concrete examples.`;
+
+async function humanizeWithAnthropic(data, options = {}) {
+  const {
+    apiKey   = process.env.ANTHROPIC_API_KEY,
+    model    = 'claude-opus-4-5',
+    mode     = 'prose',
+    lang     = 'English',
+    context  = '',
+    maxChars = 12000,
+  } = options;
+
+  if (!apiKey) {
+    throw new Error(
+      'ANTHROPIC_API_KEY is required for AI mode. ' +
+      'Set it via environment variable or --api-key flag. ' +
+      'Alternatively, use --engine local for offline processing.'
+    );
+  }
+
+  let Anthropic;
+  try { Anthropic = require('@anthropic-ai/sdk'); } catch {
+    throw new Error(
+      'The @anthropic-ai/sdk package is required for AI mode.\n' +
+      'Install it with: npm install @anthropic-ai/sdk\n' +
+      'Or use --engine local for offline processing.'
+    );
+  }
+
+  const client    = new Anthropic.default({ apiKey });
+  const jsonStr   = JSON.stringify(data, null, 2);
+  const truncated = jsonStr.length > maxChars;
+  const payload   = truncated ? jsonStr.slice(0, maxChars) + '\n\n… (truncated for length)' : jsonStr;
+
+  const userMessage = [
+    context   ? `Context: ${context}` : '',
+    `Output language: ${lang}`,
+    `Output style: ${mode === 'story' ? 'narrative story' : mode === 'markdown' ? 'markdown report' : 'clear prose paragraphs'}`,
+    truncated ? `Note: This JSON was truncated (${jsonStr.length} chars total, showing first ${maxChars}).` : '',
+    '',
+    'Here is the JSON to humanize:',
+    '```json',
+    payload,
+    '```',
+  ].filter(Boolean).join('\n');
+
+  const message = await client.messages.create({
+    model,
+    max_tokens: 1024,
+    system: SYSTEM_PROMPT,
+    messages: [{ role: 'user', content: userMessage }],
+  });
+
+  return message.content
+    .filter(b => b.type === 'text')
+    .map(b => b.text)
+    .join('')
+    .trim();
+}
+
+/**
+ * Route AI humanization to the correct provider.
+ * @param {any}    data
+ * @param {object} options
+ * @param {'anthropic'|'openai'|'ollama'} [options.aiProvider='anthropic']
+ */
+async function humanizeWithAI(data, options = {}) {
+  const provider = options.aiProvider || options.provider || 'anthropic';
+
+  switch (provider) {
+    case 'anthropic':
+      return humanizeWithAnthropic(data, options);
+
+    case 'openai': {
+      const { humanizeWithOpenAI } = require('./openai');
+      return humanizeWithOpenAI(data, options);
+    }
+
+    case 'ollama': {
+      const { humanizeWithOllama } = require('./ollama');
+      return humanizeWithOllama(data, options);
+    }
+
+    default:
+      throw new Error(`Unknown AI provider: "${provider}". Use: anthropic, openai, or ollama.`);
+  }
+}
+
+module.exports = { humanizeWithAI, humanizeWithAnthropic };

package/src/strategies/ollama.js

@@ -0,0 +1,135 @@
+'use strict';
+
+// ─────────────────────────────────────────────────────────────────────────────
+//  json-humanized · Ollama Strategy (local AI, no API key needed)
+//  Requires: Ollama running at http://localhost:11434
+//  Install:  https://ollama.ai
+// ─────────────────────────────────────────────────────────────────────────────
+
+const SYSTEM_PROMPT = `You are a JSON data interpreter. Your job is to transform raw JSON into clear, natural, human-readable prose that anyone can understand — even without technical knowledge.
+
+Rules:
+1. Write in plain English. No jargon, no code, no JSON syntax in your output.
+2. Describe what the data MEANS, not just what it contains.
+3. Use a warm, professional tone.
+4. Identify patterns: if it's a list of users, say "This is a list of 5 users…"
+5. Highlight important or unusual values.
+6. Group related fields logically in your description.
+7. If a field looks sensitive (password, token, secret), say it's hidden — don't echo it.
+8. Keep it concise but complete.
+9. Never use bullet points or markdown — write flowing paragraphs.`;
+
+/**
+ * Humanize JSON using a local Ollama model
+ * @param {any} data
+ * @param {object} options
+ * @param {string} [options.ollamaUrl='http://localhost:11434']
+ * @param {string} [options.ollamaModel='llama3']
+ * @param {string} [options.lang='English']
+ * @param {string} [options.context='']
+ * @param {number} [options.maxChars=12000]
+ */
+async function humanizeWithOllama(data, options = {}) {
+  const {
+    ollamaUrl   = process.env.OLLAMA_URL || 'http://localhost:11434',
+    ollamaModel = process.env.OLLAMA_MODEL || 'llama3',
+    lang        = 'English',
+    context     = '',
+    maxChars    = 12000,
+  } = options;
+
+  const jsonStr  = JSON.stringify(data, null, 2);
+  const truncated = jsonStr.length > maxChars;
+  const payload  = truncated ? jsonStr.slice(0, maxChars) + '\n\n… (truncated)' : jsonStr;
+
+  const prompt = [
+    SYSTEM_PROMPT,
+    '',
+    context ? `Context: ${context}` : '',
+    `Output language: ${lang}`,
+    truncated ? `Note: JSON was truncated (${jsonStr.length} chars, showing first ${maxChars}).` : '',
+    '',
+    'Here is the JSON to humanize:',
+    payload,
+  ].filter(Boolean).join('\n');
+
+  // Use native fetch (Node 18+) or fall back to https module
+  const url = `${ollamaUrl.replace(/\/$/, '')}/api/generate`;
+
+  let responseText;
+
+  try {
+    const res = await fetchJSON(url, {
+      model:  ollamaModel,
+      prompt,
+      stream: false,
+    });
+    responseText = res.response;
+  } catch (err) {
+    if (err.code === 'ECONNREFUSED' || err.message.includes('ECONNREFUSED')) {
+      throw new Error(
+        `Cannot connect to Ollama at ${ollamaUrl}.\n` +
+        'Make sure Ollama is running: https://ollama.ai\n' +
+        `And that the model is pulled: ollama pull ${ollamaModel}`
+      );
+    }
+    throw err;
+  }
+
+  return (responseText || '').trim();
+}
+
+/**
+ * Check if Ollama is reachable and the model is available.
+ * @param {string} baseUrl
+ * @param {string} model
+ * @returns {Promise<boolean>}
+ */
+async function checkOllamaHealth(baseUrl = 'http://localhost:11434', model = 'llama3') {
+  try {
+    const res = await fetchJSON(`${baseUrl.replace(/\/$/, '')}/api/tags`, null, 'GET');
+    const models = (res.models || []).map(m => m.name);
+    return models.some(m => m.startsWith(model));
+  } catch {
+    return false;
+  }
+}
+
+// ─── tiny fetch helper (no deps) ─────────────────────────────────────────────
+
+function fetchJSON(url, body, method = 'POST') {
+  return new Promise((resolve, reject) => {
+    const parsed = new URL(url);
+    const lib    = parsed.protocol === 'https:' ? require('https') : require('http');
+    const data   = body ? JSON.stringify(body) : null;
+
+    const opts = {
+      hostname: parsed.hostname,
+      port:     parsed.port || (parsed.protocol === 'https:' ? 443 : 80),
+      path:     parsed.pathname + parsed.search,
+      method,
+      headers: {
+        'Content-Type':   'application/json',
+        'Content-Length': data ? Buffer.byteLength(data) : 0,
+      },
+    };
+
+    const req = lib.request(opts, (res) => {
+      let raw = '';
+      res.on('data', c => { raw += c; });
+      res.on('end', () => {
+        try {
+          resolve(JSON.parse(raw));
+        } catch {
+          resolve({ response: raw });
+        }
+      });
+    });
+
+    req.on('error', reject);
+    if (data) req.write(data);
+    req.end();
+  });
+}
+
+module.exports = { humanizeWithOllama, checkOllamaHealth };

package/src/strategies/openai.js

@@ -0,0 +1,82 @@
+'use strict';
+
+// ─────────────────────────────────────────────────────────────────────────────
+//  json-humanized · OpenAI Strategy
+//  Requires: npm install openai
+// ─────────────────────────────────────────────────────────────────────────────
+
+const SYSTEM_PROMPT = `You are a JSON data interpreter. Your job is to transform raw JSON into clear, natural, human-readable prose that anyone can understand — even without technical knowledge.
+
+Rules:
+1. Write in plain English. No jargon, no code, no JSON syntax in your output.
+2. Describe what the data MEANS, not just what it contains.
+3. Use a warm, professional tone.
+4. Identify patterns: if it's a list of users, say "This is a list of 5 users…"
+5. Highlight important or unusual values.
+6. Group related fields logically in your description.
+7. If a field looks sensitive (password, token, secret), say it's hidden — don't echo it.
+8. Keep it concise but complete. Aim for 3–10 sentences for simple objects, more for complex ones.
+9. Never use bullet points or markdown — write flowing paragraphs.
+10. If there's a list, summarize the pattern and give 1–2 concrete examples.`;
+
+/**
+ * Humanize JSON using the OpenAI API
+ */
+async function humanizeWithOpenAI(data, options = {}) {
+  const {
+    apiKey = process.env.OPENAI_API_KEY,
+    model = 'gpt-4o-mini',
+    mode = 'prose',
+    lang = 'English',
+    context = '',
+    maxChars = 12000,
+  } = options;
+
+  if (!apiKey) {
+    throw new Error(
+      'OPENAI_API_KEY is required for OpenAI provider. ' +
+      'Set it via environment variable or --api-key flag.'
+    );
+  }
+
+  let OpenAI;
+  try {
+    OpenAI = require('openai');
+  } catch {
+    throw new Error(
+      'The "openai" package is required for OpenAI provider.\n' +
+      'Install it with: npm install openai'
+    );
+  }
+
+  const client = new OpenAI.default({ apiKey });
+
+  const jsonStr = JSON.stringify(data, null, 2);
+  const truncated = jsonStr.length > maxChars;
+  const payload = truncated ? jsonStr.slice(0, maxChars) + '\n\n… (truncated)' : jsonStr;
+
+  const userMessage = [
+    context ? `Context: ${context}` : '',
+    `Output language: ${lang}`,
+    `Output style: ${mode === 'story' ? 'narrative story' : 'clear prose paragraphs'}`,
+    truncated ? `Note: JSON was truncated (${jsonStr.length} chars, showing first ${maxChars}).` : '',
+    '',
+    'Here is the JSON to humanize:',
+    '```json',
+    payload,
+    '```',
+  ].filter(Boolean).join('\n');
+
+  const response = await client.chat.completions.create({
+    model,
+    messages: [
+      { role: 'system', content: SYSTEM_PROMPT },
+      { role: 'user',   content: userMessage },
+    ],
+    max_tokens: 1024,
+  });
+
+  return response.choices[0].message.content.trim();
+}
+
+module.exports = { humanizeWithOpenAI };

package/src/watch.js

@@ -0,0 +1,133 @@
+'use strict';
+
+/**
+ * watch.js — watch a file for changes and re-run humanization on every save.
+ * Uses Node.js built-in fs.watch; no extra dependencies.
+ */
+
+const fs   = require('fs');
+const path = require('path');
+
+const { parseAny } = require('./parsers');
+
+// ─── ANSI helpers ────────────────────────────────────────────────────────────
+
+const ESC   = '\x1b[';
+const RESET = '\x1b[0m';
+const BOLD  = '\x1b[1m';
+const DIM   = '\x1b[2m';
+const GREEN = '\x1b[32m';
+const CYAN  = '\x1b[36m';
+const YELLOW = '\x1b[33m';
+const RED   = '\x1b[31m';
+
+function clearScreen() {
+  process.stdout.write('\x1bc');
+}
+
+function timestamp() {
+  return new Date().toLocaleTimeString();
+}
+
+function header(filePath) {
+  const name = path.basename(filePath);
+  const line = '─'.repeat(52);
+  return [
+    `${CYAN}${line}${RESET}`,
+    `${BOLD}  👁  Watching: ${name}${RESET}   ${DIM}(Ctrl+C to stop)${RESET}`,
+    `${CYAN}${line}${RESET}`,
+    '',
+  ].join('\n');
+}
+
+// ─── debounce ────────────────────────────────────────────────────────────────
+
+function debounce(fn, delay) {
+  let timer;
+  return (...args) => {
+    clearTimeout(timer);
+    timer = setTimeout(() => fn(...args), delay);
+  };
+}
+
+// ─── core watch function ─────────────────────────────────────────────────────
+
+/**
+ * Watch a file and re-humanize on every change.
+ *
+ * @param {string}   filePath   path to the JSON/YAML/TOML file
+ * @param {object}   options    same options as humanize()
+ * @param {Function} humanizeFn async (data, options) => string
+ * @returns {{ stop: Function }}   call stop() to end watching
+ */
+function watch(filePath, options = {}, humanizeFn) {
+  const absPath = path.resolve(filePath);
+
+  if (!fs.existsSync(absPath)) {
+    throw new Error(`File not found: ${absPath}`);
+  }
+
+  let runCount = 0;
+
+  async function run() {
+    runCount++;
+    clearScreen();
+    process.stdout.write(header(absPath));
+    process.stdout.write(`${DIM}Run #${runCount} · ${timestamp()}${RESET}\n\n`);
+
+    let raw;
+    try {
+      raw = fs.readFileSync(absPath, 'utf8');
+    } catch (err) {
+      process.stdout.write(`${RED}Error reading file: ${err.message}${RESET}\n`);
+      return;
+    }
+
+    let data;
+    try {
+      data = parseAny(raw, absPath);
+    } catch (err) {
+      process.stdout.write(`${RED}Parse error: ${err.message}${RESET}\n`);
+      return;
+    }
+
+    try {
+      const result = await humanizeFn(data, { ...options, filename: path.basename(absPath) });
+      process.stdout.write(result + '\n');
+    } catch (err) {
+      process.stdout.write(`${RED}Humanization error: ${err.message}${RESET}\n`);
+    }
+
+    process.stdout.write(`\n${DIM}─────  Watching for changes…${RESET}\n`);
+  }
+
+  // Run immediately
+  run().catch(console.error);
+
+  // Watch for changes (debounced 200ms to avoid double-fire on some editors)
+  const debouncedRun = debounce(() => run().catch(console.error), 200);
+
+  const watcher = fs.watch(absPath, { persistent: true }, (event) => {
+    if (event === 'change' || event === 'rename') {
+      debouncedRun();
+    }
+  });
+
+  watcher.on('error', (err) => {
+    process.stderr.write(`${RED}Watch error: ${err.message}${RESET}\n`);
+  });
+
+  // Graceful shutdown
+  const cleanup = () => {
+    watcher.close();
+    process.stdout.write(`\n${YELLOW}Stopped watching.${RESET}\n`);
+    process.exit(0);
+  };
+
+  process.on('SIGINT',  cleanup);
+  process.on('SIGTERM', cleanup);
+
+  return { stop: () => watcher.close() };
+}
+
+module.exports = { watch };