onekit-tools 0.1.0__py3-none-any.whl

onekit/__init__.py

@@ -0,0 +1,10 @@
+# Copyright 2026 Mattia Piazzalunga
+# SPDX-License-Identifier: Apache-2.0
+"""OneKit's shared, offline processing API."""
+
+__version__ = "0.1.0"
+
+from .api import execute, pipeline
+from .models import Artifact, OneKitError, Result
+
+__all__ = ["Artifact", "OneKitError", "Result", "execute", "pipeline"]

onekit/__main__.py

@@ -0,0 +1,5 @@
+# Copyright 2026 Mattia Piazzalunga
+# SPDX-License-Identifier: Apache-2.0
+from .cli import main
+
+raise SystemExit(main())

onekit/api.py

@@ -0,0 +1,61 @@
+# Copyright 2026 Mattia Piazzalunga
+# SPDX-License-Identifier: Apache-2.0
+from __future__ import annotations
+
+import importlib
+
+from .catalog import TOOLS
+from .models import Artifact, OneKitError, Result
+
+MAX_BYTES = 128 * 1024 * 1024
+
+
+def execute(tool_id: str, files: list[Artifact], options: dict | None = None, *, browser=False) -> Result:
+    tool = TOOLS.get(tool_id)
+    if tool is None:
+        raise OneKitError(f"Unknown tool: {tool_id}. Run 'onekit list'.")
+    if browser and not tool.browser:
+        raise OneKitError("This tool is in development for the browser. Use the CLI.")
+    if not files:
+        raise OneKitError("Choose at least one input file.")
+    if len(files) > 256 or sum(len(file.data) for file in files) > MAX_BYTES:
+        raise OneKitError("Input exceeds the limit of 256 files or 128 MiB.")
+    if not tool.multiple and len(files) != 1:
+        raise OneKitError("This tool accepts one input file.")
+    if tool.accepts != ("*",) and any(file.kind not in tool.accepts for file in files):
+        raise OneKitError(f"Expected file types: {', '.join(tool.accepts)}.")
+    try:
+        result = importlib.import_module(f"onekit.tools.{tool.handler}").run(tool, files, dict(options or {}))
+    except OneKitError:
+        raise
+    except ImportError as exc:
+        raise OneKitError(f"Missing optional dependency '{exc.name}'. Install the matching OneKit extra; see 'onekit doctor {tool_id}'.") from exc
+    except Exception as exc:
+        raise OneKitError(f"Cannot process this input: {str(exc)[:500]}") from exc
+    if tool.fidelity == "compromise" and tool.note not in result.warnings:
+        result.warnings.insert(0, tool.note)
+    if not result.files:
+        raise OneKitError("The engine produced no output.")
+    return result
+
+
+def pipeline(steps: list[dict], files: list[Artifact], *, browser=False) -> Result:
+    if not isinstance(steps, list) or not steps or len(steps) > 16:
+        raise OneKitError("A pipeline needs between 1 and 16 steps.")
+    warnings, trace = [], []
+    for step in steps:
+        if not isinstance(step, dict) or not isinstance(step.get("options", {}), dict):
+            raise OneKitError("Each step must be an object containing a tool and an options object.")
+        tool_id = step.get("tool", "")
+        tool = TOOLS.get(tool_id)
+        if tool is None:
+            raise OneKitError(f"Unknown tool: {tool_id}.")
+        if len(files) > 1 and not tool.multiple:
+            parts = [execute(tool_id, [file], step.get("options", {}), browser=browser) for file in files]
+            result = Result([file for part in parts for file in part.files], [warning for part in parts for warning in part.warnings])
+        else:
+            result = execute(tool_id, files, step.get("options", {}), browser=browser)
+        files = result.files
+        warnings.extend(result.warnings)
+        trace.append({"tool": tool_id, "outputs": [file.name for file in files]})
+    return Result(files, list(dict.fromkeys(warnings)), {"steps": trace})

onekit/catalog.py

@@ -0,0 +1,113 @@
+# Copyright 2026 Mattia Piazzalunga
+# SPDX-License-Identifier: Apache-2.0
+"""Single source of truth for CLI discovery, web routes and runtime contracts."""
+from dataclasses import asdict, dataclass, replace
+
+
+@dataclass(frozen=True)
+class Tool:
+    id: str
+    name: str
+    group: str
+    handler: str
+    accepts: tuple[str, ...] = ("*",)
+    produces: str = "*"
+    browser: bool = False
+    fidelity: str = "exact"
+    note: str = "Preserves the selected content; validate important outputs."
+    packages: tuple[str, ...] = ()
+    engines: tuple[str, ...] = ()
+    multiple: bool = False
+    options: tuple[str, ...] = ()
+
+
+TOOLS: dict[str, Tool] = {}
+
+
+def add(id, name, group, handler, accepts=("*",), produces="*", **kwargs):
+    TOOLS[id] = Tool(id, name, group, handler, tuple(accepts), produces, **kwargs)
+
+
+CONVERSIONS = {
+    "md": ["latex", "json", "html", "pdf", "docx"],
+    "pdf": ["pdfa", "png", "jpeg", "webp", "tiff", "docx", "html", "pptx", "md"],
+    "image": ["base64", "pdf", "pptx"], "base64": ["image"],
+    "docx": ["pdf", "png", "md"], "pptx": ["pdf", "png"],
+    "latex": ["html", "pdf", "md"], "html": ["pdf", "latex", "json", "md"],
+    "xlsx": ["pdf", "csv", "json"], "json": ["xlsx"], "csv": ["xlsx", "json"],
+}
+LABELS = {"md": "Markdown", "latex": "LaTeX", "docx": "Word", "pptx": "PowerPoint", "xlsx": "Excel", "image": "Image", "base64": "Base64", "pdfa": "PDF/A", "json": "JSON", "pdf": "PDF", "notebook": "Jupyter notebook", "word": "Word"}
+IMAGE_TYPES = ("png", "jpeg", "webp", "gif", "bmp", "tiff", "ico")
+PURE = {("md", "json"), ("html", "json"), ("csv", "json"), ("base64", "image"), ("image", "base64")}
+for source, targets in CONVERSIONS.items():
+    for target in targets:
+        pair = (source, target)
+        browser = pair in PURE or pair in {("md", "html"), ("html", "md"), ("image", "pdf"), ("xlsx", "csv"), ("xlsx", "json"), ("json", "xlsx"), ("csv", "xlsx")}
+        packages = ("markdown-it-py",) if pair == ("md", "html") else ("markdownify",) if pair == ("html", "md") else ("Pillow",) if source == "image" and target != "base64" else ("openpyxl",) if "xlsx" in pair else ()
+        native = not browser
+        engine = ("pandoc",) if source in ("md", "latex", "html") and target != "pdf" else ("pdflatex",) if pair == ("latex", "pdf") else ("soffice",) if source in ("docx", "pptx", "xlsx") else ()
+        if source == "pdf":
+            packages = ("pypdfium2", "Pillow") if target in IMAGE_TYPES else ("pypdf",) if target in ("md", "html", "docx") else ("pypdfium2", "Pillow", "python-pptx") if target == "pptx" else ()
+            engine = ("gs",) if target == "pdfa" else ()
+        if pair == ("md", "pdf") or pair == ("html", "pdf"):
+            engine = ("pandoc", "pdflatex")
+        if pair == ("image", "pptx"):
+            packages = ("python-pptx",)
+        if pair == ("pdf", "docx"):
+            packages = ("pypdf", "python-docx")
+        add(f"{source}-to-{target}", f"{LABELS.get(source, source.upper())} to {LABELS.get(target, target.upper())}", "converters", "converters", IMAGE_TYPES if source == "image" else (source,), target, browser=browser, packages=packages, engines=engine, fidelity="exact" if pair in PURE and source != "html" else "compromise", note="Formatting, fonts, layout, formulas or unsupported elements may change. Scanned PDFs require OCR first." if pair not in PURE else "Structured conversion; the output represents the source data.", options=("sheet",) if source == "xlsx" else ())
+
+PDF_OPS = ["merge", "split", "remove-pages", "organize", "extract-pages", "compress", "repair", "edit", "rotate", "sign", "protect", "unlock", "validate-pdfa"]
+for operation in PDF_OPS:
+    native = operation in ("sign", "validate-pdfa")
+    add(f"pdf-{operation}", f"{operation.replace('-', ' ').capitalize()} PDF", "pdf", "pdf", ("pdf",), "pdf" if operation != "validate-pdfa" else "json", browser=not native and operation not in ("protect", "unlock"), packages=("pypdf", "reportlab") if operation == "edit" else ("pypdf",) if not native else ("pyhanko",) if operation == "sign" else (), engines=("verapdf",) if operation == "validate-pdfa" else (), multiple=operation == "merge", fidelity="compromise" if operation in ("compress", "repair", "edit", "sign") else "exact", note="Repair is best effort. Editing adds text overlays. Signing requires a PKCS#12 certificate." if operation in ("repair", "edit", "sign") else "Compression is lossless and may not reduce already optimized files." if operation == "compress" else "Page operations preserve content. Encryption permissions are advisory.", options=("pages",) if operation in ("remove-pages", "organize", "extract-pages") else ("angle",) if operation == "rotate" else ("password",) if operation in ("protect", "unlock") else ("text", "x", "y", "page") if operation == "edit" else ("certificate", "password") if operation == "sign" else ())
+
+for op in ("compress", "crop", "convert"):
+    add(f"image-{op}", f"{op.capitalize()} image", "images", "images", IMAGE_TYPES, "image", browser=True, packages=("Pillow",), fidelity="compromise" if op == "compress" else "exact", note="Lossy formats discard detail. Animation and metadata can be removed; use a lossless format to preserve pixels.", options=("format", "quality") if op != "crop" else ("box",))
+add("image-extract-pdf", "Extract images from PDF", "images", "images", ("pdf",), "image", browser=True, packages=("pypdf", "Pillow"))
+for group, formats in (("video", ("mp4", "webm", "mkv", "mov", "avi", "gif")), ("audio", ("mp3", "wav", "flac", "ogg", "aac", "m4a", "mp4"))):
+    add(f"{group}-convert", f"Convert {group}", group, "media", ("*",), "*", engines=("ffmpeg",), fidelity="compromise", note="Available codecs depend on your FFmpeg build; re-encoding can lose quality.", options=("format", "codec", "bitrate"))
+add("archive-convert", "Convert archive", "archives", "archives", ("zip", "tar", "gz", "bz2", "xz"), "*", browser=True, note="ZIP and TAR variants are supported. Archive links and unsafe paths are rejected.", options=("format",))
+add("font-convert", "Convert font", "fonts", "fonts", ("ttf", "otf", "woff", "woff2"), "*", packages=("fonttools",), note="Changes font containers; does not transform TrueType outlines into CFF outlines or vice versa.", options=("format",))
+for op in ("inspect", "metadata-set", "metadata-remove", "count", "encoding-convert"):
+    add(f"file-{op}", {"inspect": "Inspect file", "metadata-set": "Set metadata", "metadata-remove": "Remove metadata", "count": "Count text", "encoding-convert": "Convert text encoding"}[op], "inspector", "inspector", browser=op in ("inspect", "count", "encoding-convert"), produces="json" if op in ("inspect", "count") else "*", engines=("exiftool",) if op.startswith("metadata") else (), options=("metadata",) if op == "metadata-set" else ("encoding",) if op == "encoding-convert" else ())
+for op in ("encrypt", "decrypt"):
+    add(f"security-{op}", f"{op.capitalize()} files or folders", "security", "security", produces="onekit" if op == "encrypt" else "*", browser=True, packages=("pycryptodome",), options=("password",), multiple=op == "encrypt", note="Authenticated AES-256-GCM with scrypt. Losing the password makes recovery impossible.")
+
+LANGUAGES = "JavaScript TypeScript JSX TSX Python Java C C++ C# Go Rust PHP Ruby Kotlin Swift Dart Scala Lua Bash Shell PowerShell SQL HTML CSS SCSS Less XML SVG JSON JSON5 JSONC YAML TOML Markdown MDX LaTeX GraphQL Vue Svelte Astro Solidity HCL Terraform Dockerfile R Julia Elixir Haskell".split()
+VALIDATORS = LANGUAGES + ["XSD", "JSON-Schema", "CSV", "OpenAPI", "AsyncAPI"]
+MINIFIERS = "JavaScript TypeScript JSX TSX HTML CSS JSON SVG GraphQL".split()
+for operation, languages in (("format", LANGUAGES), ("validate", VALIDATORS), ("minify", MINIFIERS)):
+    for language in languages:
+        slug = language.lower().replace("++", "pp").replace("#", "sharp")
+        built_in = language == "JSON" or operation == "validate" and language in ("Python", "XML", "SVG", "TOML", "CSV")
+        add(f"dev-{operation}-{slug}", f"{operation.capitalize()} {language.replace('-', ' ')}", "developer", "developer", produces="json" if operation == "validate" else "*", browser=built_in, fidelity="compromise" if operation == "minify" else "exact", note="Validation checks the configured parser or compiler; project-wide types, imports and dependencies may require a local project.", options=())
+for target in ("pdf", "docx", "md", "latex", "html", "json"):
+    add(f"ocr-to-{target}", f"OCR to {LABELS.get(target, target.upper())}", "ocr", "ocr", ("pdf",) + IMAGE_TYPES, target, packages=("pytesseract", "Pillow", "pypdfium2", "python-docx"), engines=("tesseract",), fidelity="compromise", note="Recognition depends on scan quality and installed language packs. Equations and layout may need manual correction.", options=("language", "dpi"))
+for kind in ("text", "json", "notebook", "latex", "pdf", "word", "code"):
+    add(f"diff-{kind}", f"Compare {LABELS.get(kind, kind).replace('word', 'Word')} files", "diff", "diff", produces="json", browser=kind not in ("pdf", "word"), packages=("pypdf",) if kind == "pdf" else ("python-docx",) if kind == "word" else (), multiple=True, fidelity="compromise" if kind in ("pdf", "word", "latex") else "exact", note="Compares extracted text, not visual layout." if kind in ("pdf", "word") else "Notebook comparison can include Markdown, code or both. LaTeX text mode omits commands.", options=("mode",) if kind in ("notebook", "latex") else ())
+
+
+for id in ("docx-to-md", "md-to-docx", "image-to-pptx", "pdf-to-md", "pdf-to-html", "pdf-to-docx", "pdf-protect", "pdf-unlock", "diff-pdf", "diff-word", "font-convert", "dev-format-xml", "dev-format-svg", "dev-format-toml", "dev-validate-json5", "dev-validate-jsonc", "dev-validate-yaml", "dev-validate-json-schema", "dev-validate-xsd"):
+    TOOLS[id] = replace(TOOLS[id], browser=True, engines=())
+for id, packages in {"docx-to-md": ("python-docx",), "md-to-docx": ("python-docx",), "font-convert": ("fonttools", "brotli"), "dev-format-toml": ("tomli-w",), "dev-validate-json5": ("json5",), "dev-validate-jsonc": ("json5",), "dev-validate-yaml": ("PyYAML",), "dev-validate-json-schema": ("jsonschema",), "dev-validate-xsd": ("xmlschema",)}.items():
+    TOOLS[id] = replace(TOOLS[id], packages=packages)
+for id, tool in list(TOOLS.items()):
+    if "pypdf" in tool.packages:
+        TOOLS[id] = replace(tool, packages=("pycryptodome",) + tool.packages)
+TOOLS["file-encoding-convert"] = replace(TOOLS["file-encoding-convert"], options=("source_encoding", "encoding"))
+TOOLS["file-inspect"] = replace(TOOLS["file-inspect"], packages=("Pillow", "pycryptodome", "pypdf"))
+TOOLS["image-convert"] = replace(TOOLS["image-convert"], fidelity="compromise")
+TOOLS["image-crop"] = replace(TOOLS["image-crop"], fidelity="compromise", options=("box", "format", "quality"))
+for id in ("csv-to-json", "csv-to-xlsx"):
+    TOOLS[id] = replace(TOOLS[id], options=("delimiter",))
+for id in ("pdf-to-png", "pdf-to-jpeg", "pdf-to-webp", "pdf-to-tiff", "pdf-to-pptx"):
+    TOOLS[id] = replace(TOOLS[id], options=("dpi",))
+TOOLS["pdf-rotate"] = replace(TOOLS["pdf-rotate"], options=("angle", "pages"))
+for id in ("md-to-docx",):
+    TOOLS[id] = replace(TOOLS[id], packages=("markdown-it-py", "python-docx"))
+TOOLS["md-to-docx"] = replace(TOOLS["md-to-docx"], note="CommonMark headings, lists, emphasis and code are exported. Images, advanced layouts and Markdown extensions may need adjustment.")
+
+
+def manifest():
+    return [asdict(tool) for tool in TOOLS.values()]

onekit/cli.py

@@ -0,0 +1,190 @@
+# Copyright 2026 Mattia Piazzalunga
+# SPDX-License-Identifier: Apache-2.0
+from __future__ import annotations
+
+import argparse
+import getpass
+import gettext
+import importlib.util
+import json
+import os
+import shutil
+import sys
+import tempfile
+from pathlib import Path
+
+from . import __version__
+from .api import execute, pipeline
+from .catalog import TOOLS, manifest
+from .models import Artifact, OneKitError
+
+_ = gettext.translation("onekit", localedir=Path(__file__).parent / "locales", fallback=True).gettext
+
+PACKAGE_MODULES = {"PyYAML": "yaml", "Pillow": "PIL", "markdown-it-py": "markdown_it", "python-docx": "docx", "python-pptx": "pptx", "fonttools": "fontTools", "pycryptodome": "Crypto"}
+
+
+def doctor(tool_id=None):
+    from .tools.native import COPYLEFT, executable
+    report = []
+    for tool in ([TOOLS[tool_id]] if tool_id else TOOLS.values()):
+        packages = list(tool.packages)
+        engines = list(tool.engines)
+        if tool.group == "developer" and not tool.browser:
+            from .tools.developer import engine_for
+            engine = engine_for(tool)
+            if engine:
+                engines.append(engine)
+        missing = [name for name in packages if importlib.util.find_spec(PACKAGE_MODULES.get(name, name.replace("-", "_"))) is None]
+        blocked = [name for name in engines if name in COPYLEFT and os.environ.get("ONEKIT_ALLOW_COPYLEFT") == "0"]
+        for name in engines:
+            if name in blocked:
+                continue
+            try:
+                executable(name)
+            except OneKitError:
+                missing.append(name)
+        if "node" in engines and not (Path(os.environ.get("ONEKIT_NODE_ENGINE_PATH", Path.home() / ".cache" / "onekit" / "node")) / "node_modules").is_dir():
+            missing.append("OneKit Node engines (onekit engines install)")
+        report.append({"tool": tool.id, "ready": not missing and not blocked, "missing": missing, "policyBlocked": blocked, "browser": tool.browser})
+    return report
+
+
+def read_files(paths, folders=False):
+    files = []
+    for value in paths:
+        path = Path(value)
+        if path.is_symlink():
+            raise OneKitError("Symlink inputs are not supported.")
+        if path.is_dir() and folders:
+            for child in sorted(path.rglob("*")):
+                if child.is_symlink():
+                    raise OneKitError("Folders containing symlinks are not supported.")
+                if child.is_file():
+                    if len(files) >= 256 or child.stat().st_size > 128 * 1024 * 1024:
+                        raise OneKitError("Folder exceeds input limits.")
+                    files.append(Artifact((Path(path.name) / child.relative_to(path)).as_posix(), child.read_bytes()))
+        elif path.is_file():
+            if path.stat().st_size > 128 * 1024 * 1024:
+                raise OneKitError("File exceeds 128 MiB.")
+            files.append(Artifact(path.name, path.read_bytes()))
+        else:
+            raise OneKitError(f"Cannot read '{path}'.")
+    return files
+
+
+def write_files(result, destination, force=False):
+    target = Path(destination)
+    as_directory = len(result.files) > 1 or target.is_dir() or not target.suffix
+    paths = [(target / file.name if as_directory else target, file) for file in result.files]
+    if len({str(path.resolve()) for path, _ in paths}) != len(paths):
+        raise OneKitError("Multiple outputs have the same file name; rename the inputs.")
+    for path, _ in paths:
+        for parent in (path, *path.parents):
+            if parent.is_symlink():
+                raise OneKitError("Output paths cannot contain symlinks.")
+        if path.exists() and not force:
+            raise OneKitError(f"'{path}' already exists. Choose another destination or pass --force.")
+    for path, file in paths:
+        path.parent.mkdir(parents=True, exist_ok=True)
+        descriptor, temporary = tempfile.mkstemp(prefix=".onekit-", dir=path.parent)
+        try:
+            with os.fdopen(descriptor, "wb") as stream:
+                stream.write(file.data)
+            os.replace(temporary, path)
+        finally:
+            if os.path.exists(temporary):
+                os.unlink(temporary)
+        print(path)
+    for warning in result.warnings:
+        print(f"Warning: {warning}", file=sys.stderr)
+
+
+def parser():
+    root = argparse.ArgumentParser(prog="onekit", description=_("One simple toolkit. Your files stay yours."))
+    root.add_argument("--version", action="version", version=__version__)
+    commands = root.add_subparsers(dest="command", required=True)
+    listing = commands.add_parser("list", help="Browse all tools and their fidelity notes")
+    listing.add_argument("--json", action="store_true")
+    listing.add_argument("--group")
+    diagnosis = commands.add_parser("doctor", help="Check optional Python packages and system engines")
+    diagnosis.add_argument("tool", nargs="?", choices=TOOLS, metavar="TOOL")
+    diagnosis.add_argument("--json", action="store_true")
+    engines = commands.add_parser("engines", help="Install the optional, version-locked Node developer engines")
+    engines.add_argument("action", choices=["install"])
+    engines.add_argument("--directory", type=Path)
+    for name in ("run", "pipeline"):
+        command = commands.add_parser(name)
+        if name == "run":
+            command.add_argument("tool", choices=TOOLS, metavar="TOOL")
+            command.add_argument("--options", default="{}", help="JSON object of tool options")
+        else:
+            command.add_argument("--steps", required=True, help="JSON file with a list of {tool, options} objects")
+        command.add_argument("files", nargs="+")
+        command.add_argument("-o", "--output", required=True)
+        command.add_argument("--force", action="store_true")
+        command.add_argument("--ask-password", action="store_true", help="Read a password without exposing it in shell history")
+    return root
+
+
+def main(argv=None):
+    args = parser().parse_args(argv)
+    try:
+        if args.command == "list":
+            tools = [item for item in manifest() if not args.group or item["group"] == args.group]
+            if args.json:
+                print(json.dumps(tools, indent=2))
+            else:
+                for tool in tools:
+                    print(f"{tool['id']:34} {'browser + CLI' if tool['browser'] else 'CLI':14} {tool['fidelity']}  {tool['name']}")
+            return 0
+        if args.command == "engines":
+            install_node_engines(args.directory)
+            return 0
+        if args.command == "doctor":
+            report = doctor(args.tool)
+            if args.json:
+                print(json.dumps(report, indent=2))
+            else:
+                for item in report:
+                    print(f"{item['tool']:34} {'ready' if item['ready'] else 'needs setup'}  {', '.join(item['missing'] + item['policyBlocked'])}")
+            return 0 if all(item["ready"] for item in report) else 1
+        if args.command == "run":
+            options = json.loads(args.options)
+            if not isinstance(options, dict):
+                raise OneKitError("--options must contain a JSON object.")
+            if args.ask_password:
+                options["password"] = getpass.getpass("Password: ")
+            result = execute(args.tool, read_files(args.files, args.tool == "security-encrypt"), options)
+        else:
+            steps = json.loads(Path(args.steps).read_text(encoding="utf-8"))
+            if args.ask_password:
+                password = getpass.getpass("Password: ")
+                for step in steps:
+                    step.setdefault("options", {})["password"] = password
+            result = pipeline(steps, read_files(args.files))
+        write_files(result, args.output, args.force)
+        return 0
+    except (OneKitError, OSError, ValueError) as exc:
+        print(f"onekit: {exc}", file=sys.stderr)
+        return 2
+    except KeyboardInterrupt:
+        print("onekit: cancelled", file=sys.stderr)
+        return 130
+
+
+def install_node_engines(directory=None):
+    from .tools.native import command
+    target = directory or Path(os.environ.get("ONEKIT_NODE_ENGINE_PATH", Path.home() / ".cache" / "onekit" / "node"))
+    target.mkdir(parents=True, exist_ok=True)
+    source = Path(__file__).parent / "tools" / "developer" / "node"
+    if (target / "package.json").exists() and json.loads((target / "package.json").read_text())["name"] != "onekit-developer-engines":
+        raise OneKitError("This directory contains a different Node project; choose another destination.")
+    for name in ("package.json", "package-lock.json"):
+        shutil.copyfile(source / name, target / name)
+    command("npm", ["ci", "--ignore-scripts", "--no-fund"], target, timeout=300)
+    command("npm", ["audit", "--audit-level=low"], target)
+    print(f"Developer engines installed in {target}.")
+
+
+if __name__ == "__main__":
+    sys.exit(main())

onekit/models.py

@@ -0,0 +1,76 @@
+# Copyright 2026 Mattia Piazzalunga
+# SPDX-License-Identifier: Apache-2.0
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import PurePosixPath
+from typing import Any
+import json
+
+
+class OneKitError(ValueError):
+    """An actionable processing error, safe to show in the CLI or UI."""
+
+
+@dataclass(frozen=True)
+class Artifact:
+    name: str
+    data: bytes
+
+    def __post_init__(self):
+        name = self.name.replace("\\", "/")
+        if not name or name.startswith("/") or ".." in name.split("/") or ":" in name:
+            raise OneKitError("File names must be relative and cannot traverse directories.")
+        reserved = {"CON", "PRN", "AUX", "NUL", *(f"COM{i}" for i in range(1, 10)), *(f"LPT{i}" for i in range(1, 10))}
+        if any(ord(char) < 32 for char in name) or any(part.split(".")[0].upper() in reserved or part.endswith((" ", ".")) for part in name.split("/")):
+            raise OneKitError("This file name is not portable across supported operating systems.")
+        object.__setattr__(self, "name", name)
+
+    @property
+    def kind(self) -> str:
+        aliases = {"jpg": "jpeg", "htm": "html", "markdown": "md", "yml": "yaml", "tex": "latex"}
+        ext = PurePosixPath(self.name).suffix.lower().lstrip(".")
+        return aliases.get(ext, ext)
+
+    @property
+    def stem(self) -> str:
+        return PurePosixPath(self.name).stem
+
+    def text(self) -> str:
+        try:
+            return self.data.decode("utf-8-sig")
+        except UnicodeDecodeError as exc:
+            raise OneKitError("This operation requires UTF-8 text. Convert the encoding first.") from exc
+
+
+@dataclass
+class Result:
+    files: list[Artifact]
+    warnings: list[str] = field(default_factory=list)
+    details: dict[str, Any] = field(default_factory=dict)
+
+
+def output(source: Artifact, extension: str, data: str | bytes) -> Artifact:
+    return Artifact(f"{source.stem}.{extension}", data.encode("utf-8") if isinstance(data, str) else data)
+
+
+def require(options: dict, key: str):
+    value = options.get(key)
+    if value is None or value == "":
+        raise OneKitError(f"The '{key}' option is required.")
+    return value
+
+
+def parse_json(text: str):
+    def constant(value):
+        raise OneKitError(f"{value} is not valid standard JSON.")
+
+    def pairs(items):
+        result = {}
+        for key, value in items:
+            if key in result:
+                raise OneKitError(f"Duplicate JSON key: {key}.")
+            result[key] = value
+        return result
+
+    return json.loads(text, parse_constant=constant, object_pairs_hook=pairs)

onekit/tools/__init__.py

@@ -0,0 +1,3 @@
+# Copyright 2026 Mattia Piazzalunga
+# SPDX-License-Identifier: Apache-2.0
+"""Lazy-loaded tool families; each family owns its processing adapters."""

onekit/tools/archives/__init__.py

@@ -0,0 +1,73 @@
+# Copyright 2026 Mattia Piazzalunga
+# SPDX-License-Identifier: Apache-2.0
+import io
+import tarfile
+import zipfile
+from pathlib import PurePosixPath
+
+from ...models import Artifact, OneKitError, Result, output
+
+LIMIT = 128 * 1024 * 1024
+
+
+def safe_name(name):
+    path = PurePosixPath(name.replace("\\", "/"))
+    if path.is_absolute() or ".." in path.parts or ":" in name:
+        raise OneKitError("Archive contains an unsafe path.")
+    return str(path)
+
+
+def unpack(data):
+    files, total = [], 0
+    if zipfile.is_zipfile(io.BytesIO(data)):
+        with zipfile.ZipFile(io.BytesIO(data)) as archive:
+            entries = archive.infolist()
+            if len(entries) > 4096:
+                raise OneKitError("Archive contains too many entries.")
+            for entry in entries:
+                name = safe_name(entry.filename)
+                if entry.is_dir():
+                    continue
+                if entry.external_attr >> 16 & 0o170000 == 0o120000:
+                    raise OneKitError("Archive symlinks are not supported.")
+                total += entry.file_size
+                if total > LIMIT or entry.file_size > max(entry.compress_size, 1) * 1000:
+                    raise OneKitError("Archive expansion exceeds safety limits.")
+                files.append(Artifact(name, archive.read(entry)))
+    else:
+        with tarfile.open(fileobj=io.BytesIO(data), mode="r:*") as archive:
+            for index, entry in enumerate(archive):
+                name = safe_name(entry.name)
+                if entry.isdir():
+                    continue
+                if not entry.isfile():
+                    raise OneKitError("Archive links and devices are not supported.")
+                total += entry.size
+                if total > LIMIT or index > 4096:
+                    raise OneKitError("Archive expansion exceeds safety limits.")
+                stream = archive.extractfile(entry)
+                files.append(Artifact(name, stream.read(LIMIT + 1)))
+    return files
+
+
+def pack(files, format="zip"):
+    stream = io.BytesIO()
+    if format == "zip":
+        with zipfile.ZipFile(stream, "w", compression=zipfile.ZIP_DEFLATED) as archive:
+            for file in files:
+                archive.writestr(safe_name(file.name), file.data)
+    else:
+        modes = {"tar": "w", "tar.gz": "w:gz", "tar.bz2": "w:bz2", "tar.xz": "w:xz"}
+        if format not in modes:
+            raise OneKitError("Supported archive formats: zip, tar, tar.gz, tar.bz2, tar.xz.")
+        with tarfile.open(fileobj=stream, mode=modes[format]) as archive:
+            for file in files:
+                info = tarfile.TarInfo(safe_name(file.name))
+                info.size = len(file.data)
+                info.mode = 0o600
+                archive.addfile(info, io.BytesIO(file.data))
+    return stream.getvalue()
+
+
+def run(tool, files, options):
+    return Result([output(files[0], options.get("format", "zip"), pack(unpack(files[0].data), options.get("format", "zip")))])