json-humanized 2.0.0

package/docs/PUBLISHING.md

@@ -0,0 +1,124 @@
+# Publishing to npm
+
+Step-by-step guide for maintainers.
+
+---
+
+## Prerequisites
+
+- You have an account on [npmjs.com](https://www.npmjs.com)
+- You are logged in: `npm whoami` should print your username
+- If not: `npm login`
+
+---
+
+## First publish
+
+### 1. Check the package name is available
+
+```bash
+npm view json-humanized
+# If it returns "npm error 404" → name is free ✓
+# If it returns package info → name is taken, update "name" in package.json
+```
+
+### 2. Review what will be published
+
+```bash
+npm pack --dry-run
+```
+
+You should see only:
+- `bin/cli.js`
+- `src/**`
+- `examples/*.json`, `examples/demo.js`
+- `README.md`, `LICENSE`, `package.json`
+
+NOT included (via `.npmignore`): `test/`, `.github/`, `docs/`, `node_modules/`
+
+### 3. Run tests one final time
+
+```bash
+npm test
+```
+
+### 4. Publish
+
+```bash
+npm publish
+```
+
+That's it. Your package is live at:
+`https://www.npmjs.com/package/json-humanized`
+
+---
+
+## Publishing an update
+
+### 1. Update CHANGELOG.md
+
+Add an entry under a new version heading.
+
+### 2. Bump the version
+
+```bash
+# Patch (1.0.0 → 1.0.1): bug fixes
+npm version patch
+
+# Minor (1.0.0 → 1.1.0): new features, backwards-compatible
+npm version minor
+
+# Major (1.0.0 → 2.0.0): breaking changes
+npm version major
+```
+
+This command automatically:
+- Updates `version` in `package.json`
+- Creates a git commit: `"1.0.1"`
+- Creates a git tag: `"v1.0.1"`
+
+### 3. Push to GitHub
+
+```bash
+git push && git push --tags
+```
+
+### 4. Publish to npm
+
+```bash
+npm publish
+```
+
+---
+
+## Publish with a tag (beta)
+
+```bash
+npm version prerelease --preid=beta   # → 1.0.1-beta.0
+npm publish --tag beta
+```
+
+Users install it with: `npm install json-humanized@beta`
+
+---
+
+## Unpublish (within 72 hours only)
+
+```bash
+npm unpublish json-humanized@1.0.0
+```
+
+After 72 hours npm does not allow unpublishing — deprecate instead:
+
+```bash
+npm deprecate json-humanized@1.0.0 "Critical bug, use 1.0.1"
+```
+
+---
+
+## Checking download stats
+
+```bash
+npm info json-humanized
+# or visit: https://www.npmjs.com/package/json-humanized
+```

package/examples/api-response.json

@@ -0,0 +1,42 @@
+{
+  "data": [
+    {
+      "id": "order_001",
+      "status": "delivered",
+      "created_at": "2024-06-01T10:00:00Z",
+      "total": 129.95,
+      "customer_name": "Bob Martinez",
+      "items": [
+        { "name": "Wireless Headphones", "qty": 1, "price": 89.99 },
+        { "name": "USB-C Cable", "qty": 2, "price": 19.99 }
+      ],
+      "shipping_address": {
+        "city": "Chicago",
+        "country": "US"
+      }
+    },
+    {
+      "id": "order_002",
+      "status": "processing",
+      "created_at": "2024-06-28T09:15:00Z",
+      "total": 249.00,
+      "customer_name": "Clara Kim",
+      "items": [
+        { "name": "Mechanical Keyboard", "qty": 1, "price": 249.00 }
+      ],
+      "shipping_address": {
+        "city": "Austin",
+        "country": "US"
+      }
+    }
+  ],
+  "meta": {
+    "total": 2,
+    "page": 1,
+    "per_page": 20
+  },
+  "links": {
+    "self": "https://api.example.com/orders?page=1",
+    "next": null
+  }
+}

package/examples/demo.js

@@ -0,0 +1,50 @@
+'use strict';
+
+// json-humanized — Programmatic API demo
+
+const { humanize, humanizeFile, humanizeString } = require('../src/index');
+
+async function demo() {
+  console.log('═'.repeat(60));
+  console.log('  json-humanized · Programmatic API Demo');
+  console.log('═'.repeat(60));
+
+  // ── 1. Humanize inline data ─────────────────────────────────────
+  console.log('\n📌 Example 1: Simple object\n');
+  const result1 = await humanize({
+    name: 'Alice',
+    age: 30,
+    email: 'alice@example.com',
+    premium: true,
+    score: 9.2,
+  });
+  console.log(result1);
+
+  // ── 2. Humanize from file ───────────────────────────────────────
+  console.log('\n📌 Example 2: From file (user-profile.json)\n');
+  const result2 = await humanizeFile('./examples/user-profile.json', {
+    format: 'plain',
+  });
+  console.log(result2);
+
+  // ── 3. Markdown format ──────────────────────────────────────────
+  console.log('\n📌 Example 3: Markdown output\n');
+  const result3 = await humanizeString(
+    JSON.stringify({ errors: [{ code: 404, message: 'Not found', path: '/api/users/999' }] }),
+    { format: 'markdown' }
+  );
+  console.log(result3);
+
+  // ── 4. Story format ─────────────────────────────────────────────
+  console.log('\n📌 Example 4: Story format\n');
+  const result4 = await humanize(
+    { city: 'Paris', population: 2161000, country: 'France', latitude: 48.8566, longitude: 2.3522 },
+    { format: 'story' }
+  );
+  console.log(result4);
+}
+
+demo().catch(err => {
+  console.error('Demo failed:', err.message);
+  process.exit(1);
+});

package/examples/user-profile.json

@@ -0,0 +1,36 @@
+{
+  "user": {
+    "id": "usr_8f2a1c9d",
+    "name": "Alice Rosenberg",
+    "email": "alice@example.com",
+    "age": 29,
+    "phone": "+1-555-0147",
+    "premium": true,
+    "created_at": "2023-06-15T08:30:00Z",
+    "address": {
+      "city": "San Francisco",
+      "country": "United States",
+      "zip": "94105"
+    },
+    "preferences": {
+      "theme": "dark",
+      "notifications": true,
+      "language": "en"
+    },
+    "tags": ["designer", "beta-tester", "early-adopter"]
+  },
+  "subscription": {
+    "plan": "Pro",
+    "status": "active",
+    "price": 49.99,
+    "billing_cycle": "monthly",
+    "next_billing_date": "2024-07-15T00:00:00Z",
+    "features": ["unlimited_projects", "ai_assistant", "priority_support"]
+  },
+  "stats": {
+    "total_projects": 42,
+    "storage_used_gb": 3.7,
+    "last_login": "2024-06-28T14:22:00Z",
+    "rating": 4.8
+  }
+}

package/index.d.ts

@@ -0,0 +1,138 @@
+// Type definitions for json-humanized
+// Project: https://github.com/AceAnomDev/json-humanized
+
+export type Engine     = 'local' | 'ai';
+export type AIProvider = 'anthropic' | 'openai' | 'ollama';
+export type Format     = 'plain' | 'markdown' | 'story' | 'json';
+export type Mode       = 'structured' | 'prose' | 'story';
+
+export interface HumanizeOptions {
+  /** Processing engine. Default: 'local' */
+  engine?: Engine;
+
+  /** AI provider (only used when engine = 'ai'). Default: 'anthropic' */
+  aiProvider?: AIProvider;
+
+  /** API key for Anthropic or OpenAI. Falls back to env variable. */
+  apiKey?: string;
+
+  /** Output format. Default: 'plain' */
+  format?: Format;
+
+  /** Description style. Default: 'structured' */
+  mode?: Mode;
+
+  /** Natural language for output (AI mode). Default: 'English' */
+  lang?: string;
+
+  /** Context hint for the AI (e.g. "This is a Stripe webhook"). */
+  context?: string;
+
+  /** Source filename shown in the output header. */
+  filename?: string;
+
+  /** Max chars of JSON sent to AI. Default: 12000 */
+  maxChars?: number;
+
+  /** Path to a Handlebars (.hbs) template file for custom output. */
+  template?: string;
+
+  /** Enable AI response caching. Default: true */
+  cache?: boolean;
+
+  /** Cache TTL in seconds. Default: 3600 */
+  cacheTTL?: number;
+
+  /** Explicit path to a .jh.config.json file. Auto-detected if omitted. */
+  configPath?: string;
+
+  /** Ollama base URL. Default: 'http://localhost:11434' */
+  ollamaUrl?: string;
+
+  /** Ollama model name. Default: 'llama3' */
+  ollamaModel?: string;
+
+  /** OpenAI model. Default: 'gpt-4o-mini' */
+  openaiModel?: string;
+}
+
+export interface DiffOptions {
+  /** 'local' for rule-based diff, 'ai' for AI-powered diff. Default: 'local' */
+  engine?: Engine;
+
+  /** Output format. Default: 'plain' */
+  format?: 'plain' | 'markdown' | 'json';
+
+  /** Natural language for AI diff output. Default: 'English' */
+  lang?: string;
+
+  /** Context hint for AI diff. */
+  context?: string;
+
+  /** API key for AI diff mode. */
+  apiKey?: string;
+}
+
+export interface CacheStats {
+  entries: number;
+  totalBytes: number;
+  dir: string;
+}
+
+export interface DiffModule {
+  diff(a: unknown, b: unknown, options?: DiffOptions): Promise<string>;
+  diffFiles(fileA: string, fileB: string, options?: DiffOptions): Promise<string>;
+}
+
+export interface CacheModule {
+  buildCacheKey(data: unknown, options?: object): string;
+  readCache(key: string, ttl?: number): string | null;
+  writeCache(key: string, result: string): void;
+  clearCache(): number;
+  cacheStats(): CacheStats;
+  withCache(data: unknown, options: object, fn: () => Promise<string>, enabled?: boolean): Promise<string>;
+}
+
+export interface ConfigModule {
+  loadConfig(configPath?: string): { config: object; configPath: string | null };
+  resolveLabel(key: string, fieldLabels?: Record<string, string | null>): string | null;
+  resolveType(key: string, fieldTypes?: Record<string, string>): string | null;
+  isHidden(key: string, hiddenFields?: string[]): boolean;
+  generateExampleConfig(): string;
+}
+
+/**
+ * Humanize a parsed JavaScript value (object, array, primitive).
+ *
+ * @example
+ * import { humanize } from 'json-humanized';
+ * const text = await humanize({ name: 'Alice', age: 30 });
+ */
+export function humanize(data: unknown, options?: HumanizeOptions): Promise<string>;
+
+/**
+ * Read a JSON/YAML/TOML file from disk and humanize it.
+ *
+ * @example
+ * import { humanizeFile } from 'json-humanized';
+ * const text = await humanizeFile('./users.json', { format: 'markdown' });
+ */
+export function humanizeFile(filePath: string, options?: HumanizeOptions): Promise<string>;
+
+/**
+ * Parse and humanize a raw JSON/YAML/TOML string.
+ *
+ * @example
+ * import { humanizeString } from 'json-humanized';
+ * const text = await humanizeString('{"key":"value"}');
+ */
+export function humanizeString(rawString: string, options?: HumanizeOptions): Promise<string>;
+
+/** Diff utilities */
+export const diff: DiffModule;
+
+/** Cache utilities */
+export const cache: CacheModule;
+
+/** Config utilities */
+export const config: ConfigModule;

package/package.json

@@ -0,0 +1,71 @@
+{
+  "name": "json-humanized",
+  "version": "2.0.0",
+  "description": "Transform any JSON/YAML/TOML into human-readable prose — powered by Claude AI, OpenAI, Ollama, or built-in rule-based engine",
+  "main": "src/index.js",
+  "types": "index.d.ts",
+  "bin": {
+    "json-humanized": "./bin/cli.js",
+    "jh": "./bin/cli.js"
+  },
+  "type": "commonjs",
+  "scripts": {
+    "test": "node test/index.test.js",
+    "example": "node examples/demo.js",
+    "lint": "echo 'No linter configured'",
+    "cache:clear": "node -e \"require('./src/cache').clearCache(); console.log('Cache cleared')\"",
+    "cache:stats": "node -e \"const s=require('./src/cache').cacheStats(); console.log(s)\""
+  },
+  "keywords": [
+    "json",
+    "yaml",
+    "toml",
+    "human-readable",
+    "nlp",
+    "cli",
+    "ai",
+    "claude",
+    "openai",
+    "ollama",
+    "text-generation",
+    "data-description",
+    "json-to-text",
+    "diff",
+    "watch",
+    "developer-tools"
+  ],
+  "author": "json-humanized contributors",
+  "license": "MIT",
+  "dependencies": {
+    "chalk": "4.1.2",
+    "commander": "11.1.0",
+    "ora": "5.4.1"
+  },
+  "optionalDependencies": {
+    "@anthropic-ai/sdk": "^0.20.0",
+    "openai": "^4.0.0",
+    "js-yaml": "^4.1.0",
+    "@iarna/toml": "^2.2.5",
+    "handlebars": "^4.7.8"
+  },
+  "engines": {
+    "node": ">=14.0.0"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "examples/",
+    "docs/",
+    "index.d.ts",
+    "README.md",
+    "LICENSE"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/AceAnomDev/json-humanized.git"
+  },
+  "bugs": {
+    "url": "https://github.com/AceAnomDev/json-humanized/issues"
+  },
+  "homepage": "https://github.com/AceAnomDev/json-humanized#readme"
+}

package/src/cache.js

@@ -0,0 +1,172 @@
+'use strict';
+
+/**
+ * cache.js — file-based cache for AI responses.
+ *
+ * Saves API tokens by reusing results for identical (JSON + options) combos.
+ * Cache files are stored in ~/.jh-cache/ (or $JH_CACHE_DIR).
+ * Each entry expires after `ttl` seconds (default 3600 = 1 hour).
+ *
+ * No external dependencies — uses built-in crypto + fs.
+ */
+
+const fs     = require('fs');
+const path   = require('path');
+const crypto = require('crypto');
+const os     = require('os');
+
+// ─── cache directory ─────────────────────────────────────────────────────────
+
+function getCacheDir() {
+  return process.env.JH_CACHE_DIR || path.join(os.homedir(), '.jh-cache');
+}
+
+function ensureCacheDir() {
+  const dir = getCacheDir();
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+  return dir;
+}
+
+// ─── cache key ───────────────────────────────────────────────────────────────
+
+/**
+ * Build a stable cache key from JSON content + relevant options.
+ * We hash the combination so filenames stay short and filesystem-safe.
+ */
+function buildCacheKey(data, options = {}) {
+  const { engine, format, lang, context, aiProvider, mode } = options;
+
+  const payload = JSON.stringify({
+    data,
+    engine:     engine     || 'local',
+    format:     format     || 'plain',
+    lang:       lang       || 'English',
+    context:    context    || '',
+    aiProvider: aiProvider || 'anthropic',
+    mode:       mode       || 'structured',
+  });
+
+  return crypto.createHash('sha256').update(payload).digest('hex');
+}
+
+// ─── read / write ────────────────────────────────────────────────────────────
+
+/**
+ * Try to read a cached result.
+ * Returns the cached string, or null if miss / expired.
+ *
+ * @param {string} key   from buildCacheKey()
+ * @param {number} ttl   seconds; 0 = never expire
+ * @returns {string|null}
+ */
+function readCache(key, ttl = 3600) {
+  try {
+    const file = path.join(getCacheDir(), `${key}.json`);
+    if (!fs.existsSync(file)) return null;
+
+    const entry = JSON.parse(fs.readFileSync(file, 'utf8'));
+
+    if (ttl > 0) {
+      const ageSeconds = (Date.now() - entry.savedAt) / 1000;
+      if (ageSeconds > ttl) {
+        fs.unlinkSync(file); // clean up expired entry
+        return null;
+      }
+    }
+
+    return entry.result;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Write a result to the cache.
+ *
+ * @param {string} key
+ * @param {string} result  the humanized text to cache
+ */
+function writeCache(key, result) {
+  try {
+    ensureCacheDir();
+    const file  = path.join(getCacheDir(), `${key}.json`);
+    const entry = { savedAt: Date.now(), result };
+    fs.writeFileSync(file, JSON.stringify(entry), 'utf8');
+  } catch {
+    // Cache write failures are silent — the caller still gets a valid result
+  }
+}
+
+// ─── cache management ────────────────────────────────────────────────────────
+
+/**
+ * Delete all cache entries.
+ * @returns {number} number of files deleted
+ */
+function clearCache() {
+  const dir = getCacheDir();
+  if (!fs.existsSync(dir)) return 0;
+
+  const files = fs.readdirSync(dir).filter(f => f.endsWith('.json'));
+  for (const f of files) {
+    try { fs.unlinkSync(path.join(dir, f)); } catch {}
+  }
+  return files.length;
+}
+
+/**
+ * Return cache statistics.
+ * @returns {{ entries: number, totalBytes: number, dir: string }}
+ */
+function cacheStats() {
+  const dir = getCacheDir();
+  if (!fs.existsSync(dir)) return { entries: 0, totalBytes: 0, dir };
+
+  const files = fs.readdirSync(dir).filter(f => f.endsWith('.json'));
+  let totalBytes = 0;
+
+  for (const f of files) {
+    try {
+      totalBytes += fs.statSync(path.join(dir, f)).size;
+    } catch {}
+  }
+
+  return { entries: files.length, totalBytes, dir };
+}
+
+// ─── wrapped fetch helper ────────────────────────────────────────────────────
+
+/**
+ * Call `fn` with caching: return cached result if available, otherwise
+ * call `fn`, cache its output, and return it.
+ *
+ * @param {*}        data         JSON data (used to build the cache key)
+ * @param {object}   options      humanize options (used to build the cache key)
+ * @param {Function} fn           async () => string  — the real API call
+ * @param {boolean}  [enabled]    pass false to bypass cache entirely
+ * @returns {Promise<string>}
+ */
+async function withCache(data, options, fn, enabled = true) {
+  if (!enabled) return fn();
+
+  const ttl = options.cacheTTL != null ? options.cacheTTL : 3600;
+  const key = buildCacheKey(data, options);
+
+  const cached = readCache(key, ttl);
+  if (cached !== null) return cached;
+
+  const result = await fn();
+  writeCache(key, result);
+  return result;
+}
+
+module.exports = {
+  buildCacheKey,
+  readCache,
+  writeCache,
+  clearCache,
+  cacheStats,
+  withCache,
+};