json-humanized 2.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 json-humanized contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,351 @@
+<div align="center">
+
+# json-humanized
+
+**Transform any JSON / YAML / TOML into natural human language**
+
+[![npm version](https://img.shields.io/npm/v/json-humanized?color=00e5ff&style=flat-square)](https://www.npmjs.com/package/json-humanized)
+[![CI](https://img.shields.io/github/actions/workflow/status/AceAnomDev/json-humanized/ci.yml?branch=main&style=flat-square&label=CI)](https://github.com/AceAnomDev/json-humanized/actions)
+[![license](https://img.shields.io/npm/l/json-humanized?style=flat-square)](LICENSE)
+[![node](https://img.shields.io/node/v/json-humanized?style=flat-square&color=339933)](package.json)
+[![downloads](https://img.shields.io/npm/dm/json-humanized?style=flat-square&color=00ff9d)](https://www.npmjs.com/package/json-humanized)
+
+**[Live Demo](https://aceanomdev.github.io/json-humanized)** · [Installation](#installation) · [Usage](#usage) · [API](#api) · [Config](#config-file)
+
+</div>
+
+---
+
+## What it does
+
+```bash
+$ jh user.json
+```
+
+```
+This JSON contains a structured object with 6 fields.
+• Identifier: usr_8f3k2
+• Name: "Alice Johnson"
+• Email address: alice@example.com
+• Age: 28 years old
+• Password: *** (hidden for security)
+• Balance: $4.3K
+• Created: March 15, 2024 at 10:30 AM
+```
+
+Works **100% offline** (no API key needed) — or plug in Claude AI / OpenAI / Ollama for smarter descriptions.
+
+---
+
+## Installation
+
+```bash
+npm install -g json-humanized
+```
+
+Or use without installing:
+
+```bash
+npx json-humanized data.json
+```
+
+---
+
+## Usage
+
+### CLI
+
+```bash
+# Basic — local engine (offline, instant)
+jh data.json
+
+# YAML and TOML also work
+jh config.yaml
+jh settings.toml
+
+# AI-powered (Claude)
+jh data.json --engine ai
+
+# AI with OpenAI
+jh data.json --engine ai --provider openai
+
+# AI with local Ollama (no API key!)
+jh data.json --engine ai --provider ollama
+
+# Output formats
+jh data.json --format markdown --output report.md
+jh data.json --format story
+jh data.json --format json
+
+# Diff two files
+jh v1.json --diff v2.json
+jh v1.json --diff v2.json --format markdown
+
+# Watch mode — re-runs on every save
+jh data.json --watch
+
+# Stdin
+echo '{"name":"Alice","age":30}' | jh --stdin
+
+# Custom Handlebars template
+jh data.json --template ./report.hbs
+
+# Limit JSON chars sent to AI (saves tokens)
+jh huge.json --engine ai --max-chars 8000
+
+# Cache management
+jh --cache-stats
+jh --cache-clear
+
+# Init config/template files
+jh --init-config      # creates .jh.config.json
+jh --init-template    # creates template.hbs
+```
+
+### All CLI flags
+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `--engine <engine>` | `local` | `local` or `ai` |
+| `--provider <provider>` | `anthropic` | `anthropic`, `openai`, `ollama` |
+| `--format <format>` | `plain` | `plain`, `markdown`, `story`, `json` |
+| `--mode <mode>` | `structured` | `structured`, `prose`, `story` |
+| `--lang <lang>` | `English` | Any language (AI only) |
+| `--context <text>` | — | Context hint for AI |
+| `--api-key <key>` | env var | API key override |
+| `--max-chars <n>` | `12000` | Max chars sent to AI |
+| `--output <file>` | stdout | Save output to file |
+| `--template <file>` | — | Handlebars `.hbs` template |
+| `--diff <fileB>` | — | Compare two files |
+| `--watch` | — | Re-run on file changes |
+| `--config <file>` | auto | Explicit config file path |
+| `--cache` / `--no-cache` | `true` | Enable/disable AI caching |
+| `--cache-clear` | — | Delete all cached responses |
+| `--cache-stats` | — | Show cache info |
+| `--init-config` | — | Generate sample config |
+| `--init-template` | — | Generate sample template |
+| `--stdin` | — | Read from stdin |
+| `--silent` | — | No spinner, no banner |
+
+---
+
+## API
+
+```js
+const { humanize, humanizeFile, humanizeString } = require('json-humanized');
+
+// Parse a JS value
+const text = await humanize({ name: 'Alice', age: 30 });
+
+// From a file (JSON, YAML, or TOML)
+const text = await humanizeFile('./users.yaml', { format: 'markdown' });
+
+// From a raw string
+const text = await humanizeString('{"key":"value"}');
+
+// AI mode with caching
+const text = await humanize(data, {
+  engine:    'ai',
+  aiProvider: 'anthropic',  // or 'openai' | 'ollama'
+  format:    'plain',
+  lang:      'Russian',
+  cache:     true,
+  cacheTTL:  3600,
+});
+```
+
+### Diff
+
+```js
+const { diff } = require('json-humanized');
+
+// Compare two objects
+const result = await diff.diff(before, after);
+// "Found 3 differences: …"
+
+// Compare two files
+const result = await diff.diffFiles('v1.json', 'v2.json', { format: 'markdown' });
+```
+
+### TypeScript
+
+Full types are included — no `@types/` package needed:
+
+```ts
+import { humanize, humanizeFile, HumanizeOptions } from 'json-humanized';
+
+const opts: HumanizeOptions = { engine: 'ai', aiProvider: 'ollama', format: 'markdown' };
+const text = await humanizeFile('./data.json', opts);
+```
+
+---
+
+## Config file
+
+Create `.jh.config.json` (or run `jh --init-config`) to set defaults:
+
+```json
+{
+  "engine":   "local",
+  "format":   "plain",
+  "lang":     "English",
+  "maxChars": 12000,
+  "cache":    true,
+  "cacheTTL": 3600,
+
+  "fieldLabels": {
+    "user_id":      "User ID",
+    "txn_ref":      "Transaction reference",
+    "internal_*":   null
+  },
+
+  "fieldTypes": {
+    "invoice_no": "id",
+    "balance":    "money"
+  },
+
+  "hiddenFields": ["debug_*", "internal_hash"],
+
+  "aiProvider":   "anthropic",
+  "ollamaUrl":    "http://localhost:11434",
+  "ollamaModel":  "llama3",
+  "openaiModel":  "gpt-4o-mini"
+}
+```
+
+Config is searched upward from the current directory (like ESLint / Prettier).
+
+---
+
+## Custom templates
+
+Create a Handlebars template (or run `jh --init-template`):
+
+```hbs
+# {{filename}}
+> Generated: {{timestamp}} · Engine: {{engine}}
+
+{{humanized}}
+
+---
+*Type: {{stats.type}}, Keys: {{stats.keys}}*
+```
+
+Use it with:
+
+```bash
+jh data.json --template ./report.hbs
+```
+
+Available template variables: `{{humanized}}`, `{{filename}}`, `{{engine}}`, `{{format}}`, `{{timestamp}}`, `{{stats.type}}`, `{{stats.keys}}`, `{{stats.items}}`
+
+---
+
+## AI Providers
+
+| Provider | Env Variable | Install |
+|----------|-------------|---------|
+| `anthropic` (default) | `ANTHROPIC_API_KEY` | `npm install @anthropic-ai/sdk` |
+| `openai` | `OPENAI_API_KEY` | `npm install openai` |
+| `ollama` | none needed | [Install Ollama](https://ollama.ai) |
+
+Optional dependencies — install only what you use.
+
+---
+
+## Caching
+
+AI responses are cached by default in `~/.jh-cache/`.
+
+- Same JSON + same options → returns cached result instantly
+- Cache TTL: 1 hour (configurable)
+- Override: `jh data.json --engine ai --no-cache`
+- Clear all: `jh --cache-clear`
+- Custom dir: `JH_CACHE_DIR=/tmp/my-cache jh data.json --engine ai`
+
+---
+
+## Diff
+
+```bash
+$ jh v1.json --diff v2.json
+
+Found 3 differences:
+
+➕ Added (1):
+   + phone (phone): "555-0100"
+
+✏  Changed (2):
+   ~ name (name): "Alice" → "Alice Johnson"
+   ~ balance (balance): $4.3K → $4.5K
+```
+
+```bash
+# AI-powered diff (more natural language)
+$ jh v1.json --diff v2.json --engine ai --lang Russian
+```
+
+---
+
+## Watch mode
+
+```bash
+$ jh data.json --watch
+```
+
+Watches the file and re-runs humanization on every save. Supports local and AI engines.
+
+---
+
+## Supported file types
+
+| Extension | Notes |
+|-----------|-------|
+| `.json` | Always available |
+| `.yaml`, `.yml` | Requires `npm install js-yaml` |
+| `.toml` | Requires `npm install @iarna/toml` |
+
+---
+
+## Project structure
+
+```
+json-humanized/
+├── bin/
+│   └── cli.js                  # CLI entry point
+├── src/
+│   ├── index.js                # Public API
+│   ├── humanizer.js            # Rule-based engine
+│   ├── config.js               # Config file loader
+│   ├── cache.js                # AI response cache
+│   ├── diff.js                 # Diff engine
+│   ├── watch.js                # File watcher
+│   ├── parsers/
+│   │   └── index.js            # JSON / YAML / TOML parser
+│   ├── formatters/
+│   │   ├── index.js            # plain, markdown, story, json
+│   │   └── template.js         # Handlebars template renderer
+│   └── strategies/
+│       ├── ai.js               # AI provider router
+│       ├── openai.js           # OpenAI provider
+│       └── ollama.js           # Ollama provider
+├── docs/
+│   ├── DEMO.html               # Live browser demo
+│   └── ARCHITECTURE.md
+├── examples/
+├── test/
+├── index.d.ts                  # TypeScript types
+└── .jh.config.json             # (optional) project config
+```
+
+---
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md). Issues and PRs are welcome!
+
+---
+
+## License
+
+MIT © json-humanized contributors

package/bin/cli.js

@@ -0,0 +1,319 @@
+#!/usr/bin/env node
+'use strict';
+
+// ─────────────────────────────────────────────────────────────────────────────
+//  json-humanized · CLI v2.0
+//  Usage: jh <file> [options]
+//         jh --diff a.json b.json
+//         jh --watch file.json
+//         echo '{"key":"val"}' | jh --stdin
+// ─────────────────────────────────────────────────────────────────────────────
+
+const { program } = require('commander');
+const chalk        = require('chalk');
+const ora          = require('ora');
+const fs           = require('fs');
+const path         = require('path');
+
+const { humanizeFile, humanizeString } = require('../src/index');
+const { diff, diffFiles }              = require('../src/diff');
+const { watch }                        = require('../src/watch');
+const { clearCache, cacheStats }       = require('../src/cache');
+const { generateExampleConfig }        = require('../src/config');
+const { generateExampleTemplate }      = require('../src/formatters/template');
+const pkg = require('../package.json');
+
+// ─── banner ──────────────────────────────────────────────────────────────────
+
+function printBanner() {
+  console.log('');
+  console.log(chalk.bold.cyan('  ╔══════════════════════════════════╗'));
+  console.log(chalk.bold.cyan('  ║') + chalk.bold.white('       json-humanized  v' + pkg.version + '      ') + chalk.bold.cyan('║'));
+  console.log(chalk.bold.cyan('  ║') + chalk.gray('   Turn JSON into human language   ') + chalk.bold.cyan('║'));
+  console.log(chalk.bold.cyan('  ╚══════════════════════════════════╝'));
+  console.log('');
+}
+
+// ─── CLI definition ──────────────────────────────────────────────────────────
+
+program
+  .name('json-humanized')
+  .alias('jh')
+  .version(pkg.version, '-v, --version', 'Show version')
+  .description(chalk.cyan('Transform any JSON/YAML/TOML into natural human language\n') +
+    chalk.gray('  Supports files, stdin, diff, watch, and AI-powered descriptions'))
+
+  .argument('[file]', 'JSON/YAML/TOML file to humanize (or use --stdin)')
+
+  // ── Input
+  .option('--stdin',                    'Read from stdin instead of a file')
+  .option('--diff <fileB>',             'Compare <file> with <fileB> and describe differences')
+
+  // ── Engine & Provider
+  .option('-e, --engine <engine>',      'Engine: local (default) or ai',                'local')
+  .option('--provider <provider>',      'AI provider: anthropic, openai, ollama',       'anthropic')
+
+  // ── Output
+  .option('-f, --format <format>',      'Output format: plain, markdown, story, json',  'plain')
+  .option('-m, --mode <mode>',          'Description mode: structured, prose, story',   'structured')
+  .option('-o, --output <file>',        'Save output to a file')
+  .option('--template <file>',          'Handlebars .hbs template for custom output')
+
+  // ── AI options
+  .option('-l, --lang <lang>',          'Output language (AI mode only)',                'English')
+  .option('-c, --context <text>',       'Context hint for AI (e.g. "Stripe webhook")',   '')
+  .option('-k, --api-key <key>',        'API key (overrides env variable)')
+  .option('--max-chars <n>',            'Max JSON chars sent to AI (default 12000)',     '12000')
+
+  // ── Watch
+  .option('--watch',                    'Watch file and re-humanize on every save')
+
+  // ── Config
+  .option('--config <file>',            'Path to .jh.config.json config file')
+  .option('--init-config',              'Create a sample .jh.config.json in current directory')
+  .option('--init-template',            'Create a sample template.hbs in current directory')
+
+  // ── Cache
+  .option('--no-cache',                 'Bypass AI response cache for this run')
+  .option('--cache-clear',              'Clear all cached AI responses and exit')
+  .option('--cache-stats',              'Show cache statistics and exit')
+
+  // ── Misc
+  .option('--no-banner',                'Suppress the banner')
+  .option('--silent',                   'No spinner or banner, just output')
+
+  .addHelpText('after', `
+${chalk.bold('Examples:')}
+  ${chalk.cyan('$')} jh data.json
+  ${chalk.cyan('$')} jh data.yaml --format markdown --output report.md
+  ${chalk.cyan('$')} jh users.json --engine ai --lang Spanish
+  ${chalk.cyan('$')} jh a.json --diff b.json
+  ${chalk.cyan('$')} jh config.json --watch
+  ${chalk.cyan('$')} echo '{"name":"Alice","age":30}' | jh --stdin
+  ${chalk.cyan('$')} jh payload.json --engine ai --provider openai
+  ${chalk.cyan('$')} jh payload.json --engine ai --provider ollama
+  ${chalk.cyan('$')} jh big.json --engine ai --max-chars 8000
+  ${chalk.cyan('$')} jh data.json --template ./report.hbs
+
+${chalk.bold('Engines:')}
+  ${chalk.yellow('local')}  — Fast, offline, rule-based. No API key needed.
+  ${chalk.yellow('ai')}     — AI-powered. See --provider for supported backends.
+
+${chalk.bold('AI Providers:')}
+  ${chalk.yellow('anthropic')}  — Claude (default). Needs ANTHROPIC_API_KEY.
+  ${chalk.yellow('openai')}     — GPT models. Needs OPENAI_API_KEY.
+  ${chalk.yellow('ollama')}     — Local models (llama3, mistral…). No key needed.
+
+${chalk.bold('Formats:')}
+  ${chalk.yellow('plain')}     — Human-readable text (default)
+  ${chalk.yellow('markdown')}  — Markdown report with headers and table
+  ${chalk.yellow('story')}     — Narrative storytelling style
+  ${chalk.yellow('json')}      — JSON output with metadata
+
+${chalk.bold('Environment Variables:')}
+  ANTHROPIC_API_KEY   — API key for Claude AI engine
+  OPENAI_API_KEY      — API key for OpenAI engine
+  OLLAMA_URL          — Ollama base URL (default: http://localhost:11434)
+  OLLAMA_MODEL        — Ollama model name (default: llama3)
+  JH_CACHE_DIR        — Custom cache directory (default: ~/.jh-cache)
+`);
+
+program.parse(process.argv);
+
+// ─── Main ────────────────────────────────────────────────────────────────────
+
+async function main() {
+  const opts   = program.opts();
+  const [file] = program.args;
+  const silent = opts.silent;
+
+  if (!silent && opts.banner !== false) printBanner();
+
+  // ── Cache management commands ────────────────────────────────────────────
+  if (opts.cacheStats) {
+    const s = cacheStats();
+    console.log(chalk.cyan('  Cache statistics:'));
+    console.log(`    Directory : ${s.dir}`);
+    console.log(`    Entries   : ${s.entries}`);
+    console.log(`    Size      : ${(s.totalBytes / 1024).toFixed(1)} KB`);
+    return;
+  }
+
+  if (opts.cacheClear) {
+    const n = clearCache();
+    console.log(chalk.green(`  ✓  Cleared ${n} cached AI response(s)`));
+    return;
+  }
+
+  // ── Init commands ────────────────────────────────────────────────────────
+  if (opts.initConfig) {
+    const target = path.join(process.cwd(), '.jh.config.json');
+    fs.writeFileSync(target, generateExampleConfig(), 'utf8');
+    console.log(chalk.green(`  ✓  Created ${target}`));
+    return;
+  }
+
+  if (opts.initTemplate) {
+    const target = path.join(process.cwd(), 'template.hbs');
+    generateExampleTemplate(target);
+    console.log(chalk.green(`  ✓  Created ${target}`));
+    return;
+  }
+
+  // ── Diff mode ────────────────────────────────────────────────────────────
+  if (opts.diff) {
+    if (!file) {
+      console.error(chalk.red('  ✖  --diff requires a first file argument: jh a.json --diff b.json'));
+      process.exit(1);
+    }
+
+    const spinner = !silent ? ora({ text: chalk.cyan('Comparing files…'), color: 'cyan' }).start() : null;
+
+    try {
+      const result = await diffFiles(file, opts.diff, {
+        engine:  opts.engine,
+        format:  opts.format,
+        apiKey:  opts.apiKey || process.env.ANTHROPIC_API_KEY,
+        lang:    opts.lang,
+      });
+      spinner && spinner.succeed(chalk.green('Done!'));
+      outputResult(result, opts, silent);
+    } catch (err) {
+      spinner && spinner.fail(chalk.red('Failed'));
+      exitError(err);
+    }
+    return;
+  }
+
+  // ── Watch mode ───────────────────────────────────────────────────────────
+  if (opts.watch) {
+    if (!file) {
+      console.error(chalk.red('  ✖  --watch requires a file argument'));
+      process.exit(1);
+    }
+
+    const options = buildOptions(opts);
+    const { humanize } = require('../src/index');
+
+    watch(file, options, async (data, watchOpts) => {
+      return humanize(data, watchOpts);
+    });
+    return; // watch keeps running
+  }
+
+  // ── Standard humanize ────────────────────────────────────────────────────
+  if (!file && !opts.stdin) {
+    console.error(chalk.red('  ✖  Please provide a JSON/YAML/TOML file or use --stdin'));
+    console.error(chalk.gray('     Run `jh --help` for usage information'));
+    process.exit(1);
+  }
+
+  validateOpts(opts);
+
+  const spinner = !silent ? ora({
+    text: opts.engine === 'ai'
+      ? chalk.cyan(`Sending to ${opts.provider} AI…`)
+      : chalk.cyan('Analysing structure…'),
+    color: 'cyan',
+  }).start() : null;
+
+  try {
+    const options = buildOptions(opts);
+    let result;
+
+    if (opts.stdin) {
+      const raw = await readStdin();
+      if (!raw.trim()) {
+        spinner && spinner.fail('No input received from stdin');
+        process.exit(1);
+      }
+      result = await humanizeString(raw, options);
+    } else {
+      if (!fs.existsSync(path.resolve(file))) {
+        spinner && spinner.fail(`File not found: ${file}`);
+        process.exit(1);
+      }
+      result = await humanizeFile(file, { ...options, filename: path.basename(file) });
+    }
+
+    spinner && spinner.succeed(chalk.green('Done!'));
+    outputResult(result, opts, silent);
+
+  } catch (err) {
+    spinner && spinner.fail(chalk.red('Failed'));
+    exitError(err);
+  }
+}
+
+// ─── helpers ─────────────────────────────────────────────────────────────────
+
+function buildOptions(opts) {
+  return {
+    engine:     opts.engine,
+    aiProvider: opts.provider,
+    format:     opts.format,
+    mode:       opts.mode,
+    lang:       opts.lang,
+    context:    opts.context,
+    apiKey:     opts.apiKey || process.env.ANTHROPIC_API_KEY,
+    maxChars:   parseInt(opts.maxChars, 10) || 12000,
+    template:   opts.template,
+    cache:      opts.cache !== false,
+    configPath: opts.config,
+  };
+}
+
+function outputResult(result, opts, silent) {
+  if (opts.output) {
+    fs.writeFileSync(path.resolve(opts.output), result, 'utf8');
+    if (!silent) console.log('\n' + chalk.green(`  ✓  Saved to: ${chalk.bold(opts.output)}`));
+  } else {
+    console.log('\n' + result);
+  }
+}
+
+function validateOpts(opts) {
+  const validEngines   = ['local', 'ai'];
+  const validFormats   = ['plain', 'markdown', 'story', 'json'];
+  const validProviders = ['anthropic', 'openai', 'ollama'];
+
+  if (!validEngines.includes(opts.engine)) {
+    console.error(chalk.red(`  ✖  Unknown engine: ${opts.engine}. Use: ${validEngines.join(', ')}`));
+    process.exit(1);
+  }
+  if (!validFormats.includes(opts.format)) {
+    console.error(chalk.red(`  ✖  Unknown format: ${opts.format}. Use: ${validFormats.join(', ')}`));
+    process.exit(1);
+  }
+  if (opts.engine === 'ai' && !validProviders.includes(opts.provider)) {
+    console.error(chalk.red(`  ✖  Unknown provider: ${opts.provider}. Use: ${validProviders.join(', ')}`));
+    process.exit(1);
+  }
+
+  const apiKey = opts.apiKey || process.env.ANTHROPIC_API_KEY;
+  if (opts.engine === 'ai' && opts.provider === 'anthropic' && !apiKey) {
+    console.error(chalk.red('  ✖  Anthropic engine requires ANTHROPIC_API_KEY'));
+    console.error(chalk.yellow('     Set ANTHROPIC_API_KEY env variable, or use --api-key flag'));
+    console.error(chalk.gray('     Or switch to local engine: --engine local'));
+    process.exit(1);
+  }
+}
+
+function exitError(err) {
+  console.error('\n' + chalk.red('  Error: ') + err.message);
+  if (process.env.DEBUG) console.error(err.stack);
+  process.exit(1);
+}
+
+function readStdin() {
+  return new Promise((resolve, reject) => {
+    if (process.stdin.isTTY) return resolve('');
+    let data = '';
+    process.stdin.setEncoding('utf8');
+    process.stdin.on('data', chunk => { data += chunk; });
+    process.stdin.on('end',  () => resolve(data));
+    process.stdin.on('error', reject);
+  });
+}
+
+main();