snowkit 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Snowkit
+
+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

@@ -1,3 +1,143 @@
-# Temporary Holding Version
+# Snowkit
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Private tools that run on your computer.
+
+Snowkit merges and splits PDFs, makes QR codes, tidies JSON and SQL, counts words and more. It works from the command line, and it plugs into AI apps that support the Model Context Protocol (MCP), so your assistant can do real work on your files.
+
+Your files never leave your computer. Snowkit has no account, sends nothing over the internet and keeps no copies. It reads the files you point it to and writes the results next to them.
+
+## What it can do
+
+| Tool | What it does |
+| --- | --- |
+| `pdf_merge` | Combines two or more PDFs into one, in the order you give |
+| `pdf_split` | Splits a PDF into one file per page, every few pages, or by page ranges |
+| `pdf_extract_pages` | Copies chosen pages into a new PDF, which also reorders or drops pages |
+| `pdf_rotate` | Turns all or some pages by 90, 180 or 270 degrees |
+| `pdf_info` | Shows page count, page sizes, PDF version, form fields and document details |
+| `markdown_to_pdf` | Turns Markdown into a clean, paginated PDF |
+| `qr_code` | Makes a QR code for a link or any text, as SVG or PNG |
+| `json_format` | Pretty-prints or minifies JSON, keeping large numbers exact |
+| `json_validate` | Checks JSON, and optionally checks it against a JSON Schema |
+| `sql_format` | Formats or minifies SQL |
+| `text_stats` | Counts words, characters and sentences, with reading time and readability |
+| `text_transform` | Changes case, makes URL slugs, or removes duplicate lines |
+| `color_convert` | Converts a colour between hex, RGB, HSL, HSV and OKLCH, and checks contrast |
+| `cron_explain` | Explains a cron schedule in plain English and lists the next runs |
+
+Each result ends with a link to the matching tool on [snowkit.io](https://snowkit.io), in case you would rather see it in your browser.
+
+## Use it with your AI app
+
+You need [Node.js](https://nodejs.org) 18 or newer. There is nothing else to install: the commands below fetch Snowkit the first time it runs.
+
+### Claude Desktop
+
+Open **Settings**, then **Developer**, then **Edit Config**, and add Snowkit to `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "snowkit": {
+      "command": "npx",
+      "args": ["-y", "snowkit"]
+    }
+  }
+}
+```
+
+Restart Claude Desktop. If it cannot find `npx` on Windows, use `"command": "cmd"` and `"args": ["/c", "npx", "-y", "snowkit"]`.
+
+### Claude Code
+
+```sh
+claude mcp add snowkit -- npx -y snowkit
+```
+
+### Cursor
+
+Open **Cursor Settings**, then **MCP**, then **Add new MCP server**, or add this to `~/.cursor/mcp.json` (or `.cursor/mcp.json` inside a project):
+
+```json
+{
+  "mcpServers": {
+    "snowkit": {
+      "command": "npx",
+      "args": ["-y", "snowkit"]
+    }
+  }
+}
+```
+
+### Gemini CLI
+
+Add this to `~/.gemini/settings.json`:
+
+```json
+{
+  "mcpServers": {
+    "snowkit": {
+      "command": "npx",
+      "args": ["-y", "snowkit"]
+    }
+  }
+}
+```
+
+### Any other MCP app
+
+Snowkit is a standard MCP server over standard input and output. Point your app at the command `npx -y snowkit`.
+
+Then just ask, for example:
+
+- "Merge invoice-march.pdf and invoice-april.pdf in my Downloads folder."
+- "Pull pages 3 to 5 out of contract.pdf."
+- "Make a QR code PNG for https://example.com and save it to my desktop."
+- "Is this JSON valid?"
+
+## Use it from the command line
+
+```sh
+npx snowkit pdf merge a.pdf b.pdf -o both.pdf
+npx snowkit pdf split report.pdf --every 2
+npx snowkit pdf split report.pdf --range 1-3 --range 4-
+npx snowkit pdf extract report.pdf --pages "1, 4-6"
+npx snowkit pdf rotate scan.pdf --angle 90 --pages 2
+npx snowkit pdf info report.pdf
+npx snowkit md2pdf notes.md --page letter --numbers
+npx snowkit qr "https://example.com" -o qr.png
+npx snowkit json format data.json --sort
+npx snowkit json validate data.json --schema schema.json
+npx snowkit sql format query.sql
+npx snowkit text stats essay.txt
+npx snowkit text case title headings.txt
+npx snowkit text dedupe emails.txt --ignore-case
+npx snowkit color "#336699" --against white
+npx snowkit cron "*/15 9-17 * * 1-5"
+npx snowkit --help
+```
+
+Text commands read the file you name, or standard input when you pipe text in, so they fit into scripts:
+
+```sh
+curl -s https://api.example.com/items | npx snowkit json format
+```
+
+Install it once with `npm install -g snowkit` and you can drop the `npx`.
+
+## How it treats your files
+
+- It only reads the files you name and only writes where you ask, or next to the original when you do not say.
+- It never replaces an existing file unless you set `overwrite` (or pass `--overwrite` on the command line).
+- It never connects to the internet. Every tool runs on your own computer.
+- Password-protected PDFs are left alone, with a clear message.
+
+## Good to know
+
+- `markdown_to_pdf` uses built-in fonts that cover Western European languages. Images in the Markdown are left out.
+- `pdf_rotate` keeps everything else in the file as it was. Merging, splitting and extracting copy the pages themselves, so bookmarks and document details from the originals are not carried over.
+- Errors explain what went wrong and how to fix it, so your assistant can try again sensibly.
+
+## Licence
+
+MIT. See [LICENSE](LICENSE).

package/bin/snowkit.js

@@ -0,0 +1,19 @@
+#!/usr/bin/env node
+import { readFileSync } from "node:fs";
+
+const version = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version;
+const argv = process.argv.slice(2);
+
+if (!argv.length || (argv.length === 1 && argv[0] === "mcp")) {
+  const { startServer } = await import("../src/server.js");
+  if (process.stdin.isTTY) process.stderr.write("Snowkit " + version + " is waiting for an AI app on standard input. Press Ctrl+C to stop, or run snowkit --help for the command line tools.\n");
+  try {
+    await startServer(version);
+  } catch (e) {
+    process.stderr.write("Snowkit could not start: " + String((e && e.message) || e) + "\n");
+    process.exit(1);
+  }
+} else {
+  const { main } = await import("../src/cli.js");
+  process.exitCode = await main(argv, version);
+}

package/package.json

@@ -1,6 +1,47 @@
 {
   "name": "snowkit",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Private tools that run on your computer. Merge, split and rotate PDFs, make QR codes, format JSON and SQL, and more, from the command line or any MCP client. Your files never leave your machine.",
+  "type": "module",
+  "license": "MIT",
+  "author": "Snowkit",
+  "homepage": "https://snowkit.io",
+  "bin": {
+    "snowkit": "bin/snowkit.js"
+  },
+  "exports": {
+    ".": "./src/tools.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "mcp",
+    "mcp-server",
+    "model-context-protocol",
+    "pdf",
+    "merge-pdf",
+    "split-pdf",
+    "qr-code",
+    "json",
+    "sql-formatter",
+    "cli",
+    "privacy",
+    "offline"
+  ],
+  "scripts": {
+    "test": "node --test",
+    "sync-engine": "node scripts/sync-engine.mjs"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "1.32.1",
+    "pdf-lib": "1.17.1",
+    "zod": "4.6.5"
+  }
+}

package/src/cli.js

@@ -0,0 +1,177 @@
+import { readFileSync } from "node:fs";
+import { TOOLS, runTool, ToolError } from "./tools.js";
+import { CASES } from "./text.js";
+
+const VALUE_FLAGS = new Set(["output", "pages", "angle", "range", "every", "page", "title", "level", "size", "indent", "case", "schema", "count", "against", "format"]);
+const BOOL_FLAGS = new Set(["overwrite", "json", "sort", "minify", "numbers", "utc", "ignore-case", "remove-empty", "keep-spaces", "help", "version"]);
+const SHORT = { o: "output", h: "help", v: "version" };
+
+export class UsageError extends Error {}
+
+export function parseArgs(argv) {
+  const pos = [];
+  const flags = { range: [] };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--") {
+      pos.push(...argv.slice(i + 1));
+      break;
+    }
+    let key = null;
+    let value;
+    if (/^--[a-z]/.test(a)) {
+      const eq = a.indexOf("=");
+      key = eq > 0 ? a.slice(2, eq) : a.slice(2);
+      if (eq > 0) value = a.slice(eq + 1);
+    } else if (/^-[a-z]$/i.test(a)) {
+      key = SHORT[a.slice(1)];
+      if (!key) throw new UsageError("Unknown option " + a + ".");
+    } else {
+      pos.push(a);
+      continue;
+    }
+    if (BOOL_FLAGS.has(key)) {
+      if (value !== undefined) throw new UsageError("--" + key + " does not take a value.");
+      flags[key] = true;
+    } else if (VALUE_FLAGS.has(key)) {
+      if (value === undefined) {
+        if (i + 1 >= argv.length) throw new UsageError("--" + key + " needs a value.");
+        value = argv[++i];
+      }
+      if (key === "range") flags.range.push(value);
+      else flags[key] = value;
+    } else throw new UsageError("Unknown option --" + key + ".");
+  }
+  return { pos, flags };
+}
+
+const HELP = `Snowkit: private tools that run on your computer.
+
+Usage:
+  snowkit                      start the MCP server for AI apps (same as snowkit mcp)
+  snowkit pdf merge <a.pdf> <b.pdf> [more.pdf...] [-o out.pdf]
+  snowkit pdf split <file.pdf> [--every 2 | --range 1-3 --range 4-] [-o folder]
+  snowkit pdf extract <file.pdf> --pages "1-3, 7" [-o out.pdf]
+  snowkit pdf rotate <file.pdf> --angle 90|180|270|-90 [--pages "2, 4-6"] [-o out.pdf]
+  snowkit pdf info <file.pdf>
+  snowkit md2pdf <notes.md> [-o notes.pdf] [--page letter|a4|legal|a5] [--title "..."] [--numbers]
+  snowkit qr "<text or link>" [-o qr.svg|qr.png] [--level L|M|Q|H] [--size 512]
+  snowkit json format [file.json] [--indent 2] [--sort] [--minify] [-o out.json]
+  snowkit json validate [file.json] [--schema schema.json]
+  snowkit sql format [file.sql] [--case upper|lower|preserve] [--indent 2] [--minify] [-o out.sql]
+  snowkit text stats [file.txt]
+  snowkit text case <${CASES.join("|")}> [file.txt]
+  snowkit text slug [file.txt]
+  snowkit text dedupe [file.txt] [--ignore-case] [--remove-empty] [--keep-spaces]
+  snowkit color "<colour>" [--against "<colour>"]
+  snowkit cron "<expression>" [--count 5] [--utc]
+  snowkit tools                list the tools AI apps can use
+
+Text commands read the file given, or standard input when it is piped.
+Results that are files are saved next to the input unless -o is given.
+Existing files are never replaced unless you add --overwrite.
+Add --json to print the full result as JSON.
+
+Nothing you open with Snowkit leaves your computer. https://snowkit.io`;
+
+function readStdin() {
+  if (process.stdin.isTTY) throw new UsageError("Give a file, or pipe text in.");
+  return readFileSync(0, "utf8").replace(/^/, "");
+}
+
+function textSource(file) {
+  return file && file !== "-" ? { input: file } : { text: readStdin() };
+}
+
+function num(value, name) {
+  if (value === undefined) return undefined;
+  const n = Number(value);
+  if (!Number.isFinite(n)) throw new UsageError("--" + name + " needs a number.");
+  return n;
+}
+
+function need(value, what) {
+  if (value === undefined || value === "") throw new UsageError("Missing " + what + ". Run snowkit --help for examples.");
+  return value;
+}
+
+export function plan(pos, f) {
+  const [cmd, sub, ...rest] = pos;
+  const base = { overwrite: f.overwrite || undefined };
+  const clean = (o) => Object.fromEntries(Object.entries(o).filter(([, v]) => v !== undefined));
+  if (cmd === "pdf") {
+    const files = rest;
+    if (sub === "merge") return ["pdf_merge", clean({ ...base, inputs: files, output: f.output })];
+    if (sub === "split") return ["pdf_split", clean({ ...base, input: need(files[0], "PDF file"), every: num(f.every, "every"), ranges: f.range.length ? f.range : undefined, output_folder: f.output })];
+    if (sub === "extract") return ["pdf_extract_pages", clean({ ...base, input: need(files[0], "PDF file"), pages: need(f.pages, "--pages"), output: f.output })];
+    if (sub === "rotate") return ["pdf_rotate", clean({ ...base, input: need(files[0], "PDF file"), angle: num(need(f.angle, "--angle"), "angle"), pages: f.pages, output: f.output })];
+    if (sub === "info") return ["pdf_info", { input: need(files[0], "PDF file") }];
+    throw new UsageError("Choose a PDF command: merge, split, extract, rotate or info.");
+  }
+  if (cmd === "md2pdf") return ["markdown_to_pdf", clean({ ...base, input: need(sub, "Markdown file"), output: f.output, page: f.page, title: f.title, page_numbers: f.numbers || undefined })];
+  if (cmd === "qr") return ["qr_code", clean({ ...base, text: need(sub, "text or link"), output: f.output, format: f.format, level: f.level, size: num(f.size, "size") })];
+  if (cmd === "json") {
+    if (sub === "format") return ["json_format", clean({ ...base, ...textSource(rest[0]), indent: num(f.indent, "indent"), sort_keys: f.sort || undefined, minify: f.minify || undefined, output: f.output })];
+    if (sub === "validate") return ["json_validate", clean({ ...textSource(rest[0]), schema_path: f.schema })];
+    throw new UsageError("Choose a JSON command: format or validate.");
+  }
+  if (cmd === "sql") {
+    if (sub !== "format") throw new UsageError("Use snowkit sql format [file.sql].");
+    return ["sql_format", clean({ ...base, ...textSource(rest[0]), keyword_case: f.case, indent: num(f.indent, "indent"), minify: f.minify || undefined, output: f.output })];
+  }
+  if (cmd === "text") {
+    if (sub === "stats") return ["text_stats", textSource(rest[0])];
+    if (sub === "case") return ["text_transform", clean({ ...base, action: need(rest[0], "case name, such as title"), ...textSource(rest[1]), output: f.output })];
+    if (sub === "slug") return ["text_transform", clean({ ...base, action: "slug", ...textSource(rest[0]), output: f.output })];
+    if (sub === "dedupe") return ["text_transform", clean({ ...base, action: "dedupe", ...textSource(rest[0]), ignore_case: f["ignore-case"] || undefined, remove_empty: f["remove-empty"] || undefined, trim: f["keep-spaces"] ? false : undefined, output: f.output })];
+    throw new UsageError("Choose a text command: stats, case, slug or dedupe.");
+  }
+  if (cmd === "color" || cmd === "colour") return ["color_convert", clean({ color: need(sub, "colour"), against: f.against })];
+  if (cmd === "cron") return ["cron_explain", clean({ expression: need(sub, "cron expression"), count: num(f.count, "count"), utc: f.utc || undefined })];
+  throw new UsageError("Unknown command “" + cmd + "”. Run snowkit --help to see them all.");
+}
+
+export async function main(argv, version, io = { out: process.stdout, err: process.stderr }) {
+  const say = (stream, text) => stream.write(String(text).replace(/\n?$/, "\n"));
+  let parsed;
+  try {
+    parsed = parseArgs(argv);
+  } catch (e) {
+    say(io.err, e.message);
+    return 2;
+  }
+  const { pos, flags } = parsed;
+  if (flags.version) {
+    say(io.out, version);
+    return 0;
+  }
+  if (flags.help || pos[0] === "help") {
+    say(io.out, HELP);
+    return 0;
+  }
+  if (pos[0] === "tools") {
+    const width = Math.max(...TOOLS.map((t) => t.name.length));
+    say(io.out, TOOLS.map((t) => t.name.padEnd(width + 2) + t.description).join("\n"));
+    return 0;
+  }
+  try {
+    const [name, args] = plan(pos, flags);
+    const result = await runTool(name, args);
+    if (flags.json) say(io.out, JSON.stringify(result.data, null, 2));
+    else if (result.output !== undefined) io.out.write(result.output);
+    else say(io.out, result.text);
+    if (result.data && result.data.valid === false) return 1;
+    return 0;
+  } catch (e) {
+    if (e instanceof UsageError) {
+      say(io.err, e.message);
+      return 2;
+    }
+    if (e instanceof ToolError) {
+      say(io.err, e.message);
+      return 1;
+    }
+    say(io.err, "Something went wrong: " + String((e && e.message) || e));
+    return 1;
+  }
+}