snowkit 0.0.0-stage → 0.1.0

package/src/text.js

@@ -0,0 +1,189 @@
+import { ToolError, readTextInput, writeOutput } from "./files.js";
+import { parseJson, stringify, lineCol } from "./engine/devtools-kit.js";
+import { parseJsonText, validateJson } from "./engine/jsonkit.js";
+import { formatSql, minifySql } from "./engine/sqlformat.js";
+import { stats, convertCase, dedupeLines, slugLine } from "./engine/texttools-kit.js";
+import { readability, easeLabel, gradeLabel } from "./engine/readability.js";
+import { parseColor, toHex, formatColor, nearestName, contrastRatio, wcag, ratioText } from "./engine/colorkit.js";
+import { describe, next } from "./engine/cron.js";
+
+const MAX_TEXT = 20 * 1024 * 1024;
+const endLine = (s) => String(s).replace(/\n*$/, "\n");
+const plural = (n, one, many) => n.toLocaleString("en-CA") + " " + (n === 1 ? one : many || one + "s");
+
+export async function takeText({ text, input }, what = "text") {
+  if ((text === undefined) === (input === undefined)) throw new ToolError("Give either input (a file path) or text, not both.");
+  if (input !== undefined) {
+    const file = await readTextInput(input);
+    return { text: file.text, path: file.path };
+  }
+  const value = String(text);
+  if (value.length > MAX_TEXT) throw new ToolError("That " + what + " is too long. Save it to a file and pass the file path instead.");
+  return { text: value, path: null };
+}
+
+async function deliver(body, { output, overwrite }, summary, data = {}) {
+  if (!output) return { text: summary, output: body, data: { ...data, result: body } };
+  const path = await writeOutput(output, Buffer.from(body, "utf8"), { overwrite });
+  return { text: summary + "\nSaved to " + path + ".", data: { ...data, output: path } };
+}
+
+function parseStrict(source) {
+  try {
+    return parseJson(source);
+  } catch (e) {
+    const at = e && typeof e.pos === "number" ? lineCol(source, e.pos) : null;
+    throw new ToolError("This is not valid JSON: " + String((e && e.message) || e) + (at ? " (line " + at.line + ", column " + at.col + ")" : "") + ".");
+  }
+}
+
+export async function jsonFormat(args) {
+  const { text } = await takeText(args, "JSON");
+  if (!text.trim()) throw new ToolError("The JSON is empty.");
+  const parsed = parseStrict(text);
+  const indent = args.indent === undefined ? 2 : Number(args.indent);
+  if (!Number.isInteger(indent) || indent < 0 || indent > 8) throw new ToolError("indent must be a whole number from 0 to 8.");
+  const body = endLine(stringify(parsed.value, args.minify ? "" : " ".repeat(indent), !!args.sort_keys));
+  const notes = [];
+  if (parsed.big && parsed.big.length) notes.push(plural(parsed.big.length, "large number") + " kept with every digit.");
+  if (parsed.dupes && parsed.dupes.length) notes.push(plural(parsed.dupes.length, "duplicate key") + " found; the last value of each is kept.");
+  const summary = (args.minify ? "Minified" : "Formatted") + " the JSON" + (args.sort_keys ? " with keys sorted" : "") + "." + (notes.length ? " " + notes.join(" ") : "");
+  return deliver(body, args, summary);
+}
+
+export async function jsonValidate(args) {
+  const { text } = await takeText(args, "JSON");
+  let data;
+  try {
+    data = parseJsonText(text);
+  } catch (e) {
+    return {
+      text: "Not valid JSON. " + e.message + ".",
+      data: { valid: false, syntax: { line: e.line || null, column: e.column || null, message: e.reason || e.message } },
+    };
+  }
+  let dupes = [];
+  try {
+    dupes = parseJson(text).dupes || [];
+  } catch (e) {
+    dupes = [];
+  }
+  const dupeNote = dupes.length ? "\nNote: " + plural(dupes.length, "duplicate key") + ", where only the last value counts." : "";
+  if (args.schema === undefined && args.schema_path === undefined) {
+    return { text: "Valid JSON." + dupeNote, data: { valid: true, duplicate_keys: dupes.length } };
+  }
+  if (args.schema !== undefined && args.schema_path !== undefined) throw new ToolError("Give either schema or schema_path, not both.");
+  let schema;
+  try {
+    schema = args.schema_path !== undefined ? parseJsonText((await readTextInput(args.schema_path, "schema path")).text) : typeof args.schema === "string" ? parseJsonText(args.schema) : args.schema;
+  } catch (e) {
+    if (e instanceof ToolError) throw e;
+    throw new ToolError("The schema is not valid JSON. " + e.message + ".");
+  }
+  const errors = validateJson(data, schema);
+  if (!errors.length) return { text: "Valid JSON, and it matches the schema." + dupeNote, data: { valid: true, schema_errors: [] } };
+  const shown = errors.slice(0, 50).map((e) => "  " + e.path + ": " + e.message).join("\n");
+  return {
+    text: "Valid JSON, but it does not match the schema (" + plural(errors.length, "problem") + "):\n" + shown + (errors.length > 50 ? "\n  and " + (errors.length - 50) + " more" : ""),
+    data: { valid: false, schema_errors: errors },
+  };
+}
+
+export async function sqlFormat(args) {
+  const { text } = await takeText(args, "SQL");
+  if (!text.trim()) throw new ToolError("The SQL is empty.");
+  const keywordCase = args.keyword_case || "upper";
+  const indent = args.indent === undefined ? 2 : Number(args.indent);
+  if (!Number.isInteger(indent) || indent < 1 || indent > 8) throw new ToolError("indent must be a whole number from 1 to 8.");
+  const body = endLine(args.minify ? minifySql(text, { keywordCase }) : formatSql(text, { keywordCase, indent: " ".repeat(indent) }));
+  return deliver(body, args, (args.minify ? "Minified" : "Formatted") + " the SQL.");
+}
+
+export async function textStats(args) {
+  const { text } = await takeText(args);
+  const s = stats(text);
+  const r = readability(text);
+  const lines = [
+    "Words: " + s.words.toLocaleString("en-CA"),
+    "Characters: " + s.chars.toLocaleString("en-CA") + " (" + s.nospace.toLocaleString("en-CA") + " without spaces)",
+    "Sentences: " + s.sentences.toLocaleString("en-CA"),
+    "Paragraphs: " + s.paragraphs.toLocaleString("en-CA"),
+    "Lines: " + s.lines.toLocaleString("en-CA"),
+    "Reading time: " + s.read,
+    "Speaking time: " + s.speak,
+  ];
+  const data = { words: s.words, characters: s.chars, characters_without_spaces: s.nospace, sentences: s.sentences, paragraphs: s.paragraphs, lines: s.lines, reading_time: s.read, speaking_time: s.speak };
+  if (r && r.words >= 30) {
+    lines.push("Readability (English): " + r.fleschEase + " Flesch reading ease, " + easeLabel(r.fleschEase).toLowerCase() + "; " + gradeLabel(r.averageGrade).toLowerCase() + " level");
+    if (r.longSentences.length) lines.push("Sentences over 25 words: " + r.longSentences.length);
+    data.readability = { flesch_reading_ease: r.fleschEase, ease: easeLabel(r.fleschEase), flesch_kincaid_grade: r.fleschKincaid, gunning_fog: r.gunningFog, smog: r.smog, coleman_liau: r.colemanLiau, ari: r.ari, average_grade: r.averageGrade, words_per_sentence: r.wordsPerSentence, long_sentences: r.longSentences.length };
+  }
+  return { text: lines.join("\n"), data };
+}
+
+export const CASES = ["upper", "lower", "title", "sentence", "camel", "pascal", "snake", "kebab", "constant"];
+export const TRANSFORMS = [...CASES, "slug", "dedupe"];
+
+export async function textTransform(args) {
+  const { text } = await takeText(args);
+  const action = String(args.action || "");
+  if (!TRANSFORMS.includes(action)) throw new ToolError("action must be one of: " + TRANSFORMS.join(", ") + ".");
+  if (action === "dedupe") {
+    const r = dedupeLines(text, { trim: args.trim !== false, ignoreCase: !!args.ignore_case, dropEmpty: !!args.remove_empty });
+    const removed = r.dupes ? plural(r.dupes, "duplicate line") + " removed" : "No duplicate lines found";
+    return deliver(endLine(r.out.join("\n")), args, removed + (r.empties ? ", plus " + plural(r.empties, "empty line") : "") + ".", { removed: r.dupes, empty_removed: r.empties });
+  }
+  if (action === "slug") {
+    const slugs = text.replace(/\r\n?/g, "\n").split("\n").filter((l) => l.trim()).map((l) => slugLine(l, { ascii: true, lower: true, sep: "-", stop: false, max: 0 }));
+    return deliver(endLine(slugs.join("\n")), args, "Made " + plural(slugs.length, "slug") + ".");
+  }
+  const body = convertCase(text, action === "constant" ? "constant" : action);
+  return deliver(body, args, "Converted to " + action + " case.");
+}
+
+function readColor(value) {
+  try {
+    return parseColor(String(value == null ? "" : value).trim()) || null;
+  } catch (e) {
+    return null;
+  }
+}
+
+export function colorConvert({ color, against }) {
+  const c = readColor(color);
+  if (!c) throw new ToolError("“" + color + "” does not look like a colour. Try #336699, rgb(51 102 153), hsl(210 50% 40%) or a name such as teal.");
+  const near = nearestName(c);
+  const data = { hex: toHex(c), rgb: formatColor(c, "rgb"), hsl: formatColor(c, "hsl"), hsv: formatColor(c, "hsv"), oklch: formatColor(c, "oklch"), name: near.name, exact_name: !!near.exact };
+  const lines = ["Hex: " + data.hex, "RGB: " + data.rgb, "HSL: " + data.hsl, "HSV: " + data.hsv, "OKLCH: " + data.oklch, (near.exact ? "Name: " : "Nearest name: ") + near.name];
+  if (against !== undefined && against !== null && against !== "") {
+    const b = readColor(against);
+    if (!b) throw new ToolError("“" + against + "” does not look like a colour.");
+    const ratio = contrastRatio(c, b);
+    const w = wcag(ratio);
+    const yes = (v) => (v ? "pass" : "fail");
+    Object.assign(data, { against: toHex(b), contrast: ratioText(ratio), aa_normal: !!w.aaNormal, aa_large: !!w.aaLarge, aaa_normal: !!w.aaaNormal });
+    lines.push("", "Contrast with " + data.against + ": " + data.contrast, "WCAG AA normal text: " + yes(w.aaNormal) + ", AA large text: " + yes(w.aaLarge) + ", AAA normal text: " + yes(w.aaaNormal));
+  }
+  return { text: lines.join("\n"), data };
+}
+
+export function cronExplain({ expression, count = 5, utc = false }) {
+  const expr = String(expression == null ? "" : expression).trim();
+  if (!expr) throw new ToolError("Give a cron expression, such as */15 9-17 * * 1-5.");
+  const n = Number(count);
+  if (!Number.isInteger(n) || n < 1 || n > 50) throw new ToolError("count must be a whole number from 1 to 50.");
+  let words;
+  let runs;
+  try {
+    words = describe(expr);
+    runs = next(expr, n, new Date(), { utc: !!utc });
+  } catch (e) {
+    throw new ToolError("That cron expression does not work: " + String((e && e.message) || e) + ".");
+  }
+  const zone = utc ? "UTC" : Intl.DateTimeFormat().resolvedOptions().timeZone || "local time";
+  const show = (d) => (utc ? d.toISOString().replace("T", " ").replace(/:00\.000Z$/, " UTC") : d.toLocaleString("en-CA", { dateStyle: "medium", timeStyle: "short" }));
+  return {
+    text: words + "\n\nNext runs (" + zone + "):\n" + runs.map((d) => "  " + show(d)).join("\n"),
+    data: { description: words, time_zone: zone, next_runs: runs.map((d) => d.toISOString()) },
+  };
+}

package/src/tools.js

@@ -0,0 +1,223 @@
+import { z } from "zod";
+import { mergePdfs, splitPdf, extractPages, rotatePdf, pdfInfo, markdownToPdf } from "./pdf.js";
+import { makeQr } from "./qr.js";
+import { jsonFormat, jsonValidate, sqlFormat, textStats, textTransform, colorConvert, cronExplain, TRANSFORMS } from "./text.js";
+import { ToolError } from "./files.js";
+
+export { ToolError };
+
+const SITE = "https://snowkit.io/";
+
+const path = (what) => z.string().min(1).describe(what);
+const outputPath = (fallback) => z.string().min(1).optional().describe("Where to save the result. " + fallback);
+const overwrite = z.boolean().optional().describe("Replace the output file if it already exists. Defaults to false.");
+const textOrFile = {
+  text: z.string().optional().describe("The text itself. Use this or input."),
+  input: z.string().min(1).optional().describe("Path to a file to read instead of text."),
+};
+const saveText = {
+  output: z.string().min(1).optional().describe("Save the result to this file instead of returning it."),
+  overwrite,
+};
+
+export const TOOLS = [
+  {
+    name: "pdf_merge",
+    title: "Merge PDFs",
+    description: "Combine two or more PDF files into one, in the order given. Saves next to the first file as name-merged.pdf unless output is set.",
+    link: "merge-pdf",
+    schema: {
+      inputs: z.array(z.string().min(1)).min(2).describe("Paths of the PDF files, in order."),
+      output: outputPath("Defaults to the first file's name with -merged, in the same folder."),
+      overwrite,
+    },
+    run: mergePdfs,
+  },
+  {
+    name: "pdf_split",
+    title: "Split a PDF",
+    description: "Split a PDF into several files: one per page by default, every N pages, or one file for each page range. Files are saved beside the original unless output_folder is set.",
+    link: "split-pdf",
+    schema: {
+      input: path("Path of the PDF to split."),
+      ranges: z.array(z.string().min(1)).min(1).optional().describe("One file per range, such as [\"1-3\", \"4-10\", \"11-\"]."),
+      every: z.number().int().min(1).optional().describe("Start a new file every this many pages. Defaults to 1."),
+      output_folder: z.string().min(1).optional().describe("An existing folder for the new files. Defaults to the original's folder."),
+      overwrite,
+    },
+    run: splitPdf,
+  },
+  {
+    name: "pdf_extract_pages",
+    title: "Extract PDF pages",
+    description: "Copy chosen pages of a PDF into a new PDF, in the order listed. Also works to reorder, duplicate or drop pages. Saves as name-extracted.pdf beside the original unless output is set.",
+    link: "extract-pages-from-pdf",
+    schema: {
+      input: path("Path of the PDF."),
+      pages: z.string().min(1).describe("Pages in order, such as \"1-3, 7, 10-\", \"5-1\" for reverse, \"odd\", \"even\" or \"last\"."),
+      output: outputPath("Defaults to the original's name with -extracted, in the same folder."),
+      overwrite,
+    },
+    run: extractPages,
+  },
+  {
+    name: "pdf_rotate",
+    title: "Rotate PDF pages",
+    description: "Turn all or some pages of a PDF by 90, 180 or 270 degrees clockwise, or -90 for anticlockwise. Everything else in the file is kept. Saves as name-rotated.pdf unless output is set.",
+    link: "rotate-pdf",
+    schema: {
+      input: path("Path of the PDF."),
+      angle: z.union([z.literal(90), z.literal(180), z.literal(270), z.literal(-90)]).describe("Degrees clockwise: 90, 180, 270, or -90."),
+      pages: z.string().min(1).optional().describe("Which pages to turn, such as \"2, 4-6\". Defaults to all pages."),
+      output: outputPath("Defaults to the original's name with -rotated, in the same folder."),
+      overwrite,
+    },
+    run: rotatePdf,
+  },
+  {
+    name: "pdf_info",
+    title: "PDF details",
+    description: "Read a PDF's page count, page sizes, file size, PDF version, form fields, password protection and document details such as title and author. Changes nothing.",
+    link: "edit-pdf-metadata",
+    readOnly: true,
+    schema: { input: path("Path of the PDF.") },
+    run: pdfInfo,
+  },
+  {
+    name: "markdown_to_pdf",
+    title: "Markdown to PDF",
+    description: "Turn Markdown into a clean, paginated PDF with headings, lists, tables, code blocks and links. Uses built-in fonts for Western European text; images are left out. Saves beside the Markdown file unless output is set.",
+    link: "markdown-to-pdf",
+    schema: {
+      input: z.string().min(1).optional().describe("Path to a Markdown file. Use this or markdown."),
+      markdown: z.string().optional().describe("The Markdown text itself. Needs an output path."),
+      output: outputPath("Defaults to the Markdown file's name with .pdf, in the same folder."),
+      page: z.enum(["letter", "a4", "legal", "a5"]).optional().describe("Paper size. Defaults to Letter or A4 based on the computer's region."),
+      title: z.string().optional().describe("Document title. Defaults to the first heading."),
+      page_numbers: z.boolean().optional().describe("Add page numbers at the foot of each page."),
+      overwrite,
+    },
+    run: markdownToPdf,
+  },
+  {
+    name: "qr_code",
+    title: "Make a QR code",
+    description: "Make a QR code for a link or any text, as SVG or PNG. Without an output path the SVG is returned as text. The content lives in the code itself, so it never expires.",
+    link: "qr-code",
+    schema: {
+      text: z.string().min(1).describe("The link or text to encode."),
+      output: z.string().min(1).optional().describe("File to save, ending in .svg or .png."),
+      format: z.enum(["svg", "png"]).optional().describe("Defaults to the output file's extension, or svg."),
+      level: z.enum(["L", "M", "Q", "H"]).optional().describe("Error correction: L 7%, M 15%, Q 25%, H 30%. Defaults to M."),
+      size: z.number().int().min(64).max(4096).optional().describe("Width in pixels. Defaults to 512."),
+      overwrite,
+    },
+    run: makeQr,
+  },
+  {
+    name: "json_format",
+    title: "Format JSON",
+    description: "Pretty-print or minify JSON, optionally sorting keys. Large numbers keep every digit and errors point to the line and column.",
+    link: "json-formatter",
+    schema: {
+      ...textOrFile,
+      indent: z.number().int().min(0).max(8).optional().describe("Spaces per level. Defaults to 2."),
+      sort_keys: z.boolean().optional().describe("Sort object keys A to Z."),
+      minify: z.boolean().optional().describe("Put everything on one line."),
+      ...saveText,
+    },
+    run: jsonFormat,
+  },
+  {
+    name: "json_validate",
+    title: "Validate JSON",
+    description: "Check that JSON is valid and, optionally, that it matches a JSON Schema. Reports the line and column of syntax errors and the path of every schema problem.",
+    link: "json-validator",
+    readOnly: true,
+    schema: {
+      ...textOrFile,
+      schema: z.string().optional().describe("A JSON Schema as text."),
+      schema_path: z.string().min(1).optional().describe("Path to a JSON Schema file."),
+    },
+    run: jsonValidate,
+  },
+  {
+    name: "sql_format",
+    title: "Format SQL",
+    description: "Tidy SQL into readable, indented lines, or minify it onto one line. Works with common dialects such as PostgreSQL, MySQL, SQLite and SQL Server.",
+    link: "sql-formatter",
+    schema: {
+      ...textOrFile,
+      keyword_case: z.enum(["upper", "lower", "preserve"]).optional().describe("How to write keywords. Defaults to upper."),
+      indent: z.number().int().min(1).max(8).optional().describe("Spaces per level. Defaults to 2."),
+      minify: z.boolean().optional().describe("Put the query on one line and drop comments."),
+      ...saveText,
+    },
+    run: sqlFormat,
+  },
+  {
+    name: "text_stats",
+    title: "Text statistics",
+    description: "Count words, characters, sentences, paragraphs and lines, estimate reading and speaking time, and score readability for English text.",
+    link: "word-counter",
+    readOnly: true,
+    schema: { ...textOrFile },
+    run: textStats,
+  },
+  {
+    name: "text_transform",
+    title: "Transform text",
+    description: "Change text case (upper, lower, title, sentence, camel, pascal, snake, kebab, constant), turn each line into a URL slug, or remove duplicate lines while keeping the original order.",
+    link: (args) => (args && args.action === "slug" ? "slug-generator" : args && args.action === "dedupe" ? "remove-duplicate-lines" : "case-converter"),
+    schema: {
+      ...textOrFile,
+      action: z.enum(TRANSFORMS).describe("What to do."),
+      ignore_case: z.boolean().optional().describe("For dedupe: treat Apple and apple as the same line."),
+      remove_empty: z.boolean().optional().describe("For dedupe: also drop empty lines."),
+      trim: z.boolean().optional().describe("For dedupe: ignore spaces at the start and end of lines when comparing. Defaults to true."),
+      ...saveText,
+    },
+    run: textTransform,
+  },
+  {
+    name: "color_convert",
+    title: "Convert a colour",
+    description: "Show a colour as hex, RGB, HSL, HSV and OKLCH with its nearest named colour. Give a second colour to get the WCAG contrast ratio and pass or fail results.",
+    link: (args) => (args && args.against ? "contrast-checker" : "color-converter"),
+    readOnly: true,
+    schema: {
+      color: z.string().min(1).describe("Such as #336699, rgb(51 102 153), hsl(210 50% 40%) or teal."),
+      against: z.string().min(1).optional().describe("A second colour, such as a background, to check contrast."),
+    },
+    run: colorConvert,
+  },
+  {
+    name: "cron_explain",
+    title: "Explain a cron schedule",
+    description: "Describe a five-field cron expression in plain English and list its next run times.",
+    link: "cron-expression",
+    readOnly: true,
+    schema: {
+      expression: z.string().min(1).describe("Such as \"*/15 9-17 * * 1-5\"."),
+      count: z.number().int().min(1).max(50).optional().describe("How many upcoming runs to list. Defaults to 5."),
+      utc: z.boolean().optional().describe("List times in UTC instead of this computer's time zone."),
+    },
+    run: cronExplain,
+  },
+];
+
+export function findTool(name) {
+  return TOOLS.find((t) => t.name === name);
+}
+
+export function toolLink(tool, args) {
+  const slug = typeof tool.link === "function" ? tool.link(args) : tool.link;
+  return SITE + slug + "/";
+}
+
+export async function runTool(name, args = {}) {
+  const tool = findTool(name);
+  if (!tool) throw new ToolError("Unknown tool: " + name);
+  const result = await tool.run(args);
+  return { ...result, link: toolLink(tool, args) };
+}