@wrongstack/tools 0.275.1 → 0.276.3

package/dist/json.d.ts

@@ -1,18 +1,43 @@
 import { Tool } from '@wrongstack/core';
 
+type JsonAction = 'parse' | 'query' | 'validate' | 'transform' | 'merge';
 interface JsonInput {
+    /** Operation to perform. Defaults to 'parse'. */
+    action?: JsonAction | undefined;
+    /** Path to JSON/JSON5/YAML file (alternative to `data`). */
     file?: string | undefined;
+    /** Inline JSON/JSON5/YAML string (alternative to `file`). */
     data?: string | undefined;
-    query?: string | undefined;
+    /** Output format for parse/query/transform results. */
     format?: 'json' | 'json5' | 'yaml' | undefined;
     validate?: boolean | undefined;
+    /** JMESPath-like query expression. */
+    query?: string | undefined;
+    /** Ordered JMESPath transforms (transform action only). */
+    transforms?: string[] | undefined;
+    /** JSON Schema to validate against. */
+    schema?: Record<string, unknown> | undefined;
+    /** Base object for merge. */
+    base?: unknown | undefined;
+    /** Patch object for merge. */
+    patch?: unknown | undefined;
+    /** Merge conflict resolution: 'prefer-patch' (default) or 'prefer-base'. */
+    conflictResolution?: 'prefer-base' | 'prefer-patch' | undefined;
 }
 interface JsonOutput {
     data: unknown;
     formatted: string;
     type: string;
+    action: string;
     keys?: string[] | undefined;
     query_result?: unknown | undefined;
+    result?: unknown | undefined;
+    valid?: boolean | undefined;
+    errors?: string[] | undefined;
+    steps?: Array<{
+        transform: string;
+        result: unknown;
+    }> | undefined;
     error?: string | undefined;
 }
 declare const jsonTool: Tool<JsonInput, JsonOutput>;

package/dist/json.js

@@ -1,11 +1,67 @@
 import * as fs from 'node:fs/promises';
+import * as Core from '@wrongstack/core';
+import { deepMerge } from '@wrongstack/core';
+import * as path from 'node:path';
+
+// src/json.ts
+function resolvePath(input, ctx) {
+  return path.isAbsolute(input) ? path.normalize(input) : path.resolve(ctx.workingDir ?? ctx.cwd, input);
+}
+function allowedRoots(ctx) {
+  return [path.resolve(ctx.projectRoot), path.resolve(Core.wstackGlobalRoot())];
+}
+function isInsideAny(target, roots) {
+  return roots.some((root) => {
+    const rel = path.relative(root, target);
+    return rel === "" || !rel.startsWith("..") && !path.isAbsolute(rel);
+  });
+}
+function ensureInsideRoot(absPath, ctx) {
+  const target = path.resolve(absPath);
+  if (ctx.allowOutsideProjectRoot) return target;
+  if (isInsideAny(target, allowedRoots(ctx))) return target;
+  throw new Error(`Path "${absPath}" is outside project root "${path.resolve(ctx.projectRoot)}"`);
+}
+function safeResolve(input, ctx) {
+  return ensureInsideRoot(resolvePath(input, ctx), ctx);
+}
+async function assertRealInsideRoot(absPath, ctx) {
+  if (ctx.allowOutsideProjectRoot) return;
+  const realRoots = await Promise.all(
+    allowedRoots(ctx).map((r) => fs.realpath(r).catch(() => path.resolve(r)))
+  );
+  let probe = absPath;
+  for (; ; ) {
+    let real;
+    try {
+      real = await fs.realpath(probe);
+    } catch (err) {
+      if (err.code === "ENOENT") {
+        const parent = path.dirname(probe);
+        if (parent === probe) return;
+        probe = parent;
+        continue;
+      }
+      throw err;
+    }
+    if (isInsideAny(real, realRoots)) return;
+    throw new Error(
+      `Path "${absPath}" resolves through a symlink outside project root "${realRoots[0]}"`
+    );
+  }
+}
+async function safeResolveReal(input, ctx) {
+  const abs = safeResolve(input, ctx);
+  await assertRealInsideRoot(abs, ctx);
+  return abs;
+}
 
 // src/json.ts
 var jsonTool = {
   name: "json",
   category: "Data",
-  description: "Parse, pretty-print, query, and convert between JSON, JSON5, and YAML. Supports simple path-based queries.",
-  usageHint: "VERY USEFUL FOR DATA INSPECTION:\n\n- Use on package.json, tsconfig, config files, or any structured data.\n- `query` lets you extract specific values without reading the whole file.\n- Great for validating that a file has the expected structure.\nPrefer this over raw `read` + manual parsing when dealing with configuration or data files.",
+  description: "Parse, pretty-print, query, validate, transform, and merge JSON/JSON5/YAML. Use `action` to select the operation: parse (default), query, validate, transform, or merge.",
+  usageHint: 'VERY USEFUL FOR DATA INSPECTION:\n\n- `action: "parse"` (default): read/pretty-print/convert JSON, JSON5, or YAML from `file` or `data`.\n- `action: "query"`: JMESPath-like query (`a.b[0].c`, `items[*].name`, filters, functions).\n- `action: "validate"`: validate data against a JSON Schema (`schema` param).\n- `action: "transform"`: chain multiple JMESPath transforms (`transforms` param).\n- `action: "merge"`: deep merge `base` and `patch` objects (`conflictResolution` param).\nPrefer this over raw `read` + manual parsing when dealing with configuration or data files.',
   permission: "auto",
   mutating: false,
   timeoutMs: 5e3,
@@ -14,70 +70,421 @@ var jsonTool = {
   inputSchema: {
     type: "object",
     properties: {
-      file: { type: "string", description: "Path to JSON/JSON5/YAML file" },
-      data: { type: "string", description: "JSON/JSON5/YAML string (alternative to file)" },
-      query: {
+      action: {
         type: "string",
-        description: 'JMESPath-like query (e.g. "a.b[0].c" or "a[*].name")'
+        enum: ["parse", "query", "validate", "transform", "merge"],
+        description: "Operation (default: parse). parse=read/pretty-print, query=JMESPath, validate=schema, transform=chained queries, merge=deep merge."
       },
+      file: { type: "string", description: "Path to JSON/JSON5/YAML file (parse/query/validate)" },
+      data: { type: "string", description: "JSON/JSON5/YAML string (parse/query/validate, alternative to file)" },
       format: {
         type: "string",
         enum: ["json", "json5", "yaml"],
-        description: "Output format (default: json)"
+        description: "Output format for parse/query/transform (default: json)"
+      },
+      query: {
+        type: "string",
+        description: "JMESPath-like query expression (query action)"
+      },
+      transforms: {
+        type: "array",
+        items: { type: "string" },
+        description: "Ordered JMESPath query strings (transform action)"
+      },
+      schema: {
+        type: "object",
+        description: "JSON Schema to validate against (validate action)"
+      },
+      base: { description: "Base JSON object (merge action)" },
+      patch: { description: "Patch JSON object to merge in (merge action)" },
+      conflictResolution: {
+        type: "string",
+        enum: ["prefer-base", "prefer-patch"],
+        description: "Merge conflict resolution (default: prefer-patch)"
       },
       validate: {
         type: "boolean",
-        description: "Validate syntax only, no output (default: false)"
+        description: "Validate syntax only, no output (parse action, default: false)"
       }
     }
   },
-  async execute(input) {
-    const format = input.format ?? "json";
-    let parsed;
-    let raw;
-    if (input.file) {
-      try {
-        raw = await fs.readFile(input.file, "utf8");
-      } catch {
-        return { data: null, formatted: "", type: "unknown", error: `Could not read file` };
-      }
-    } else if (input.data) {
-      raw = input.data;
-    } else {
-      return { data: null, formatted: "", type: "unknown", error: "Provide file or data" };
+  async execute(input, ctx) {
+    const action = input.action ?? "parse";
+    switch (action) {
+      case "query":
+        return executeQuery(input, ctx);
+      case "validate":
+        return executeValidate(input, ctx);
+      case "transform":
+        return executeTransform(input, ctx);
+      case "merge":
+        return executeMerge(input);
+      case "parse":
+      default:
+        return executeParse(input, ctx);
     }
+  }
+};
+async function executeParse(input, ctx) {
+  const format = input.format ?? "json";
+  let parsed;
+  let raw;
+  if (input.file) {
     try {
-      parsed = JSON.parse(raw);
-    } catch (e) {
-      return {
-        data: null,
-        formatted: "",
-        type: "unknown",
-        /* v8 ignore next -- JSON.parse only throws SyntaxError (an Error); the String(e) side is defensive. */
-        error: `Parse failed: ${e instanceof Error ? e.message : String(e)}`
-      };
-    }
-    if (input.validate) {
-      return {
-        data: parsed,
-        formatted: "valid",
-        type: Array.isArray(parsed) ? "array" : typeof parsed,
-        keys: typeof parsed === "object" && parsed !== null ? Object.keys(parsed) : void 0
-      };
-    }
-    const queryResult = input.query ? query(parsed, input.query) : void 0;
-    const formatted = formatOutput(queryResult ?? parsed, format);
+      raw = await fs.readFile(await safeResolveReal(input.file, ctx), "utf8");
+    } catch {
+      return { data: null, formatted: "", type: "unknown", action: "parse", error: "Could not read file" };
+    }
+  } else if (input.data) {
+    raw = input.data;
+  } else {
+    return { data: null, formatted: "", type: "unknown", action: "parse", error: "Provide file or data" };
+  }
+  try {
+    parsed = JSON.parse(raw);
+  } catch (e) {
+    return {
+      data: null,
+      formatted: "",
+      type: "unknown",
+      action: "parse",
+      /* v8 ignore next -- JSON.parse only throws SyntaxError (an Error); the String(e) side is defensive. */
+      error: `Parse failed: ${e instanceof Error ? e.message : String(e)}`
+    };
+  }
+  if (input.validate) {
+    return {
+      data: parsed,
+      formatted: "valid",
+      type: Array.isArray(parsed) ? "array" : typeof parsed,
+      action: "parse",
+      keys: typeof parsed === "object" && parsed !== null ? Object.keys(parsed) : void 0
+    };
+  }
+  if (input.query) {
+    const queryResult = simpleQuery(parsed, input.query);
+    const formatted2 = formatOutput(queryResult, format);
     return {
       data: parsed,
-      formatted,
+      formatted: formatted2,
       type: Array.isArray(parsed) ? "array" : typeof parsed,
+      action: "parse",
       keys: typeof parsed === "object" && parsed !== null ? Object.keys(parsed) : void 0,
       query_result: queryResult
     };
   }
-};
-function query(data, path) {
-  const parts = path.replace(/\[(\d+)\]/g, ".$1").split(".").filter(Boolean);
+  const formatted = formatOutput(parsed, format);
+  return {
+    data: parsed,
+    formatted,
+    type: Array.isArray(parsed) ? "array" : typeof parsed,
+    action: "parse",
+    keys: typeof parsed === "object" && parsed !== null ? Object.keys(parsed) : void 0
+  };
+}
+async function executeQuery(input, ctx) {
+  if (!input.query) {
+    return { data: null, formatted: "", type: "unknown", action: "query", error: "query is required for action: query" };
+  }
+  let parsed;
+  if (input.file) {
+    try {
+      const raw = await fs.readFile(await safeResolveReal(input.file, ctx), "utf8");
+      parsed = JSON.parse(raw);
+    } catch {
+      return { data: null, formatted: "", type: "unknown", action: "query", error: "Could not read/parse file" };
+    }
+  } else if (input.data) {
+    try {
+      parsed = JSON.parse(input.data);
+    } catch {
+      return { data: null, formatted: "", type: "unknown", action: "query", error: "Could not parse data string" };
+    }
+  } else {
+    return { data: null, formatted: "", type: "unknown", action: "query", error: "Provide file or data" };
+  }
+  try {
+    const result = jmespathSearch(parsed, input.query);
+    const format = input.format ?? "json";
+    return {
+      data: parsed,
+      formatted: formatOutput(result, format),
+      type: result === null ? "null" : Array.isArray(result) ? "array" : typeof result,
+      action: "query",
+      query_result: result
+    };
+  } catch (e) {
+    return {
+      data: null,
+      formatted: "",
+      type: "unknown",
+      action: "query",
+      /* v8 ignore next -- defensive String(e) */
+      error: `Query failed: ${e instanceof Error ? e.message : String(e)}`
+    };
+  }
+}
+async function executeValidate(input, ctx) {
+  if (!input.schema) {
+    return { data: null, formatted: "", type: "unknown", action: "validate", error: "schema is required for action: validate" };
+  }
+  let parsed;
+  if (input.file) {
+    try {
+      const raw = await fs.readFile(await safeResolveReal(input.file, ctx), "utf8");
+      parsed = JSON.parse(raw);
+    } catch {
+      return { data: null, formatted: "", type: "unknown", action: "validate", error: "Could not read/parse file" };
+    }
+  } else if (input.data) {
+    try {
+      parsed = JSON.parse(input.data);
+    } catch {
+      return { data: null, formatted: "", type: "unknown", action: "validate", error: "Could not parse data string" };
+    }
+  } else {
+    return { data: null, formatted: "", type: "unknown", action: "validate", error: "Provide file or data" };
+  }
+  try {
+    const { valid, errors } = validateJsonSchema(parsed, input.schema);
+    return {
+      data: parsed,
+      formatted: valid ? "valid" : "invalid",
+      type: Array.isArray(parsed) ? "array" : typeof parsed,
+      action: "validate",
+      valid,
+      errors
+    };
+  } catch (e) {
+    return {
+      data: null,
+      formatted: "",
+      type: "unknown",
+      action: "validate",
+      /* v8 ignore next -- defensive String(e) */
+      error: `Validation failed: ${e instanceof Error ? e.message : String(e)}`
+    };
+  }
+}
+async function executeTransform(input, ctx) {
+  if (!input.transforms || input.transforms.length === 0) {
+    return { data: null, formatted: "", type: "unknown", action: "transform", error: "transforms array is required for action: transform" };
+  }
+  let parsed;
+  if (input.file) {
+    try {
+      const raw = await fs.readFile(await safeResolveReal(input.file, ctx), "utf8");
+      parsed = JSON.parse(raw);
+    } catch {
+      return { data: null, formatted: "", type: "unknown", action: "transform", error: "Could not read/parse file" };
+    }
+  } else if (input.data) {
+    try {
+      parsed = JSON.parse(input.data);
+    } catch {
+      return { data: null, formatted: "", type: "unknown", action: "transform", error: "Could not parse data string" };
+    }
+  } else {
+    return { data: null, formatted: "", type: "unknown", action: "transform", error: "Provide file or data" };
+  }
+  try {
+    let current = parsed;
+    const steps = [];
+    for (const t of input.transforms) {
+      current = jmespathSearch(current, t);
+      steps.push({ transform: t, result: current });
+    }
+    const format = input.format ?? "json";
+    return {
+      data: parsed,
+      formatted: formatOutput(current, format),
+      type: current === null ? "null" : Array.isArray(current) ? "array" : typeof current,
+      action: "transform",
+      result: current,
+      steps
+    };
+  } catch (e) {
+    return {
+      data: null,
+      formatted: "",
+      type: "unknown",
+      action: "transform",
+      /* v8 ignore next -- defensive String(e) */
+      error: `Transform failed: ${e instanceof Error ? e.message : String(e)}`
+    };
+  }
+}
+async function executeMerge(input) {
+  if (input.base === void 0 || input.patch === void 0) {
+    return { data: null, formatted: "", type: "unknown", action: "merge", error: "base and patch are required for action: merge" };
+  }
+  const conflictResolution = input.conflictResolution ?? "prefer-patch";
+  try {
+    const result = deepMerge(input.base, input.patch, { conflictResolution });
+    const format = input.format ?? "json";
+    return {
+      data: result,
+      formatted: formatOutput(result, format),
+      type: result === null ? "null" : Array.isArray(result) ? "array" : typeof result,
+      action: "merge",
+      result
+    };
+  } catch (e) {
+    return {
+      data: null,
+      formatted: "",
+      type: "unknown",
+      action: "merge",
+      /* v8 ignore next -- defensive String(e) */
+      error: `Merge failed: ${e instanceof Error ? e.message : String(e)}`
+    };
+  }
+}
+function jmespathSearch(data, query) {
+  if (!query || query === "@") return data;
+  if (query === "$") return data;
+  const dotMatch = query.match(/^([a-zA-Z_][a-zA-Z0-9_]*)(?:\.(.+))?$/);
+  if (dotMatch) {
+    const key = dotMatch[1];
+    const rest = dotMatch[2];
+    const val = data?.[key];
+    if (rest === void 0) return val;
+    return jmespathSearch(val, rest);
+  }
+  const arrMatch = query.match(/^\[(\d+)\](?:\.(.+))?$/);
+  if (arrMatch) {
+    const idx = Number.parseInt(arrMatch[1], 10);
+    const rest = arrMatch[2];
+    const arr = data;
+    const val = arr?.[idx];
+    if (rest === void 0) return val;
+    return jmespathSearch(val, rest);
+  }
+  if (query === "[*]") {
+    if (Array.isArray(data)) {
+      return data;
+    }
+    return data;
+  }
+  const multiMatch = query.match(/^([a-zA-Z_][a-zA-Z0-9_]*)\[\*\](?:\.(.+))?$/);
+  if (multiMatch) {
+    const key = multiMatch[1];
+    const rest = multiMatch[2];
+    const arr = data?.[key];
+    if (!Array.isArray(arr)) return [];
+    if (rest === void 0) return arr;
+    return arr.map((item) => jmespathSearch(item, rest));
+  }
+  const filterMatch = query.match(/^\[\\?([a-zA-Z_][a-zA-Z0-9_]*)(==|!=|<|>|<=|>=)(`[^`]+`|'[^']*')\](?:\.(.+))?$/);
+  if (filterMatch) {
+    const field = filterMatch[1];
+    const op = filterMatch[2];
+    const rawVal = filterMatch[3];
+    const rest = filterMatch[4];
+    const cmpVal = JSON.parse(rawVal.slice(1, -1));
+    const arr = data;
+    if (!Array.isArray(arr)) return [];
+    const filtered = arr.filter((item) => {
+      const itemVal = item[field];
+      switch (op) {
+        case "==":
+          return itemVal === cmpVal;
+        case "!=":
+          return itemVal !== cmpVal;
+        case ">":
+          return Number(itemVal) > Number(cmpVal);
+        case "<":
+          return Number(itemVal) < Number(cmpVal);
+        case ">=":
+          return Number(itemVal) >= Number(cmpVal);
+        case "<=":
+          return Number(itemVal) <= Number(cmpVal);
+        /* v8 ignore next -- op is constrained to the six operators by the filter regex; default is unreachable. */
+        default:
+          return true;
+      }
+    });
+    if (rest === void 0) return filtered;
+    return filtered.map((item) => jmespathSearch(item, rest));
+  }
+  const fnMatch = query.match(/^(length|keys|values|type)\(@\)$/);
+  if (fnMatch) {
+    const fn = fnMatch[1];
+    switch (fn) {
+      case "length":
+        if (Array.isArray(data)) return data.length;
+        if (typeof data === "string") return data.length;
+        if (typeof data === "object" && data !== null) return Object.keys(data).length;
+        return 0;
+      case "keys":
+        if (typeof data === "object" && data !== null && !Array.isArray(data)) return Object.keys(data);
+        return [];
+      case "values":
+        if (typeof data === "object" && data !== null && !Array.isArray(data)) return Object.values(data);
+        return [];
+      case "type":
+        if (data === null) return "null";
+        if (Array.isArray(data)) return "array";
+        return typeof data;
+      /* v8 ignore next 2 -- fn is constrained to the four names by the function regex; default is unreachable. */
+      default:
+        return null;
+    }
+  }
+  return null;
+}
+function validateJsonSchema(data, schema) {
+  const errors = [];
+  function check(value, s, path2) {
+    if (s["type"]) {
+      const expectedType = s["type"];
+      const actualType = Array.isArray(value) ? "array" : value === null ? "null" : typeof value;
+      if (expectedType === "integer") {
+        if (!Number.isInteger(value)) errors.push(`${path2}: expected integer, got ${actualType}`);
+      } else if (expectedType !== actualType) {
+        errors.push(`${path2}: expected ${expectedType}, got ${actualType}`);
+      }
+    }
+    if (typeof value === "string" && s["format"] === "uri" && value) {
+      try {
+        new URL(value);
+      } catch {
+        errors.push(`${path2}: not a valid URI`);
+      }
+    }
+    if (typeof value === "string" && s["pattern"]) {
+      const re = new RegExp(s["pattern"]);
+      if (!re.test(value)) errors.push(`${path2}: does not match pattern ${s["pattern"]}`);
+    }
+    if (typeof value === "string" && s["minLength"] !== void 0 && value.length < s["minLength"]) {
+      errors.push(`${path2}: string too short (min ${s["minLength"]})`);
+    }
+    if (typeof value === "string" && s["maxLength"] !== void 0 && value.length > s["maxLength"]) {
+      errors.push(`${path2}: string too long (max ${s["maxLength"]})`);
+    }
+    if (typeof value === "number" && s["minimum"] !== void 0 && value < s["minimum"]) {
+      errors.push(`${path2}: below minimum ${s["minimum"]}`);
+    }
+    if (typeof value === "number" && s["maximum"] !== void 0 && value > s["maximum"]) {
+      errors.push(`${path2}: above maximum ${s["maximum"]}`);
+    }
+    if (Array.isArray(value) && s["items"] && Array.isArray(s["items"])) {
+      for (let i = 0; i < value.length; i++) {
+        check(value[i], s["items"], `${path2}[${i}]`);
+      }
+    }
+    if (typeof value === "object" && value !== null && !Array.isArray(value) && s["properties"]) {
+      const props = s["properties"];
+      for (const [k, propSchema] of Object.entries(props)) {
+        check(value[k], propSchema, `${path2}.${k}`);
+      }
+    }
+  }
+  check(data, schema, "$");
+  return { valid: errors.length === 0, errors };
+}
+function simpleQuery(data, path2) {
+  const parts = path2.replace(/\[(\d+)\]/g, ".$1").split(".").filter(Boolean);
   let current = data;
   for (const part of parts) {
     if (current === null || current === void 0) return void 0;