hugpy-tools 0.2.2__tar.gz

hugpy_tools-0.2.2/LICENSE

@@ -0,0 +1,41 @@
+hugpy — Source-Available License
+
+Copyright (c) 2026 putkoff (hugpy.ai). All rights reserved.
+
+Permission is granted, free of charge, to use this software ("hugpy") for
+personal and non-commercial purposes, and for time-limited commercial
+evaluation, subject to the following conditions:
+
+1. Non-commercial use means use by an individual for personal purposes, or
+   use by a non-profit or educational institution for its own internal
+   purposes. Any use by, for, or on behalf of a for-profit business or in
+   connection with revenue-generating activity is commercial use — including
+   internal business use, use in producing goods or services, and use on
+   paid engagements.
+
+2. Commercial use requires a commercial license from the copyright holder.
+   Exception: a business may evaluate the software internally for up to
+   thirty (30) days free of charge; continued use after that requires a
+   commercial license.
+
+3. Redistribution of this software, in source or binary form, modified or
+   unmodified, is not permitted without prior written permission from the
+   copyright holder. Downloading the software from an official distribution
+   channel (PyPI, npm, hugpy.ai) is not redistribution.
+
+4. Modification for personal use or internal evaluation is permitted;
+   distribution of modified versions is not.
+
+5. This notice must be retained in all copies or substantial portions of
+   the software.
+
+6. Any use outside these terms automatically terminates this license.
+
+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
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+IN THE SOFTWARE.
+
+For commercial licensing or redistribution permission: https://hugpy.ai

hugpy_tools-0.2.2/PKG-INFO

@@ -0,0 +1,93 @@
+Metadata-Version: 2.4
+Name: hugpy-tools
+Version: 0.2.2
+Summary: Hugpy tools: a slim, stdlib-only capability suite for autonomous agents (safe file/path ops, text chunking and diffing, hashing, structured-data read/write, and urllib+html.parser webpage assessment)
+Author-email: putkoff <support@hugpy.ai>
+License-Expression: LicenseRef-Proprietary
+Project-URL: Homepage, https://hugpy.ai
+Project-URL: Documentation, https://github.com/hugpy/hugpy/blob/main/py/foundation/hugpy_tools/README.md
+Project-URL: Repository, https://github.com/hugpy/hugpy
+Project-URL: Source, https://github.com/hugpy/hugpy/tree/main/py/foundation/hugpy_tools
+Project-URL: Issues, https://github.com/hugpy/hugpy/issues
+Project-URL: Changelog, https://github.com/hugpy/hugpy/releases
+Project-URL: Architecture, https://github.com/hugpy/hugpy/blob/main/PARTITION.md
+Keywords: hugpy,agent,tools,filesystem,webpage,assessment
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: toml
+Requires-Dist: tomli; python_version < "3.11" and extra == "toml"
+Provides-Extra: yaml
+Requires-Dist: PyYAML; extra == "yaml"
+Provides-Extra: render
+Requires-Dist: playwright; extra == "render"
+Provides-Extra: test
+Requires-Dist: pytest>=8; extra == "test"
+Requires-Dist: pytest-timeout; extra == "test"
+Dynamic: license-file
+
+# hugpy-tools
+
+`hugpy_tools` — a slim, **stdlib-only** capability suite for autonomous agents,
+extracted from `abstract_utilities` / `abstract_webtools` and rebuilt with no
+third-party runtime dependency. Foundation layer: it imports no other `hugpy_*`
+package, so it can be lifted out as its own distribution unchanged.
+
+Ownership and allowed dependencies are declared in `py/partition.toml`; see
+`PARTITION.md` at the workspace root.
+
+Allowed Python dependencies inside the ecosystem: **none** (stdlib only).
+
+## Built-in tools
+
+Every `fs` function takes an **already-confined** absolute path — call
+`paths.confine(root, path)` first to enforce a workspace jail (rejects `..`,
+absolute-outside, and symlink escapes in one check).
+
+| Module | Function | What it does |
+| --- | --- | --- |
+| `paths` | `confine(root, path, for_write=False)` | Resolve a path under `root`; raise `PathEscape` on any escape. |
+| `paths` | `file_parts(path)` | Decompose into dir/base/name/ext + two enclosing dir levels. |
+| `paths` | `sanitize_filename(name)` | Reduce to one safe path component, length-bounded. |
+| `fs` | `read_text(path, max_bytes=None)` | Read with encoding detection (BOM → utf-8 → cp1252). |
+| `fs` | `read_lines(path, start, end, number=False)` | 1-based inclusive line-range read. |
+| `fs` | `atomic_write(path, content, append=False)` | Durable write (temp file + `os.replace`); append supported. |
+| `fs` | `edit_replace(path, old, new, count=None)` | Exact string replace with an occurrence-count contract; atomic. |
+| `fs` | `file_info(path, hash_files=False)` | Size, mtime, type, symlink flag, optional sha256. |
+| `fs` | `list_dir(path, glob=None, ...)` | Immediate entries (dirs first), optional fnmatch. |
+| `fs` | `tree(path, max_depth=3, max_entries=500)` | Bounded recursive tree text (never follows dir symlinks). |
+| `hashkit` | `sha256_text` / `sha256_file` / `quick_hash` | Content hashing (files streamed in 1 MiB windows). |
+| `text` | `count_tokens(text)` | Dependency-free approximate BPE token count. |
+| `text` | `chunk_by_lines` / `chunk_by_tokens` | Chunk on line or token budgets (paragraph-aware). |
+| `text` | `unified_diff(before, after)` | Unified diff between two texts. |
+| `data` | `read_data(path, fmt=None)` | Parse JSON always, TOML via stdlib `tomllib`, YAML if PyYAML present. |
+| `data` | `write_json(path, obj)` / `safe_json_dumps(obj)` | Atomic JSON write / non-exploding dumps. |
+| `timekit` | `now_iso` / `now_epoch` / `epoch_to_iso` / `iso_to_epoch` | UTC time conversions. |
+| `web` | `assess_webpage(url, ...)` | assessManager-parity structured page assessment over urllib + `html.parser`. |
+| `web` | `prescreen_webpage(url, ...)` | Cheap title + description + lede relevance pre-screen. |
+
+### Web assessment
+
+`assess_webpage` returns the same dict shape as
+`abstract_webtools.assessManager.assess_webpage`
+(`{url, title, description, text, metadata, jsonld, links, truncated, render}`)
+plus additive keys `final_url`, `status`, `canonical`, `lang`, `headings`, and
+`error`. The fetch is http(s)-only, refuses redirects to other schemes,
+disables `file://` / `ftp://`, caps the body, times out, handles gzip/deflate,
+and detects charset (Content-Type → BOM → `<meta charset>` → utf-8 → cp1252).
+
+JS rendering is opt-in and lazy: `force_render=True` (or an automatic fall-back
+when the cheap fetch yields almost no text) drives a headless browser **only if
+Playwright or Selenium is installed**, and raises a clear "install X" error
+otherwise. The default path never needs a browser.
+
+## Layer
+
+Foundation. `hugpy_tools` imports no other `hugpy_*` package. The `search`
+subpackage is owned by a separate work-stream.

hugpy_tools-0.2.2/README.md

@@ -0,0 +1,59 @@
+# hugpy-tools
+
+`hugpy_tools` — a slim, **stdlib-only** capability suite for autonomous agents,
+extracted from `abstract_utilities` / `abstract_webtools` and rebuilt with no
+third-party runtime dependency. Foundation layer: it imports no other `hugpy_*`
+package, so it can be lifted out as its own distribution unchanged.
+
+Ownership and allowed dependencies are declared in `py/partition.toml`; see
+`PARTITION.md` at the workspace root.
+
+Allowed Python dependencies inside the ecosystem: **none** (stdlib only).
+
+## Built-in tools
+
+Every `fs` function takes an **already-confined** absolute path — call
+`paths.confine(root, path)` first to enforce a workspace jail (rejects `..`,
+absolute-outside, and symlink escapes in one check).
+
+| Module | Function | What it does |
+| --- | --- | --- |
+| `paths` | `confine(root, path, for_write=False)` | Resolve a path under `root`; raise `PathEscape` on any escape. |
+| `paths` | `file_parts(path)` | Decompose into dir/base/name/ext + two enclosing dir levels. |
+| `paths` | `sanitize_filename(name)` | Reduce to one safe path component, length-bounded. |
+| `fs` | `read_text(path, max_bytes=None)` | Read with encoding detection (BOM → utf-8 → cp1252). |
+| `fs` | `read_lines(path, start, end, number=False)` | 1-based inclusive line-range read. |
+| `fs` | `atomic_write(path, content, append=False)` | Durable write (temp file + `os.replace`); append supported. |
+| `fs` | `edit_replace(path, old, new, count=None)` | Exact string replace with an occurrence-count contract; atomic. |
+| `fs` | `file_info(path, hash_files=False)` | Size, mtime, type, symlink flag, optional sha256. |
+| `fs` | `list_dir(path, glob=None, ...)` | Immediate entries (dirs first), optional fnmatch. |
+| `fs` | `tree(path, max_depth=3, max_entries=500)` | Bounded recursive tree text (never follows dir symlinks). |
+| `hashkit` | `sha256_text` / `sha256_file` / `quick_hash` | Content hashing (files streamed in 1 MiB windows). |
+| `text` | `count_tokens(text)` | Dependency-free approximate BPE token count. |
+| `text` | `chunk_by_lines` / `chunk_by_tokens` | Chunk on line or token budgets (paragraph-aware). |
+| `text` | `unified_diff(before, after)` | Unified diff between two texts. |
+| `data` | `read_data(path, fmt=None)` | Parse JSON always, TOML via stdlib `tomllib`, YAML if PyYAML present. |
+| `data` | `write_json(path, obj)` / `safe_json_dumps(obj)` | Atomic JSON write / non-exploding dumps. |
+| `timekit` | `now_iso` / `now_epoch` / `epoch_to_iso` / `iso_to_epoch` | UTC time conversions. |
+| `web` | `assess_webpage(url, ...)` | assessManager-parity structured page assessment over urllib + `html.parser`. |
+| `web` | `prescreen_webpage(url, ...)` | Cheap title + description + lede relevance pre-screen. |
+
+### Web assessment
+
+`assess_webpage` returns the same dict shape as
+`abstract_webtools.assessManager.assess_webpage`
+(`{url, title, description, text, metadata, jsonld, links, truncated, render}`)
+plus additive keys `final_url`, `status`, `canonical`, `lang`, `headings`, and
+`error`. The fetch is http(s)-only, refuses redirects to other schemes,
+disables `file://` / `ftp://`, caps the body, times out, handles gzip/deflate,
+and detects charset (Content-Type → BOM → `<meta charset>` → utf-8 → cp1252).
+
+JS rendering is opt-in and lazy: `force_render=True` (or an automatic fall-back
+when the cheap fetch yields almost no text) drives a headless browser **only if
+Playwright or Selenium is installed**, and raises a clear "install X" error
+otherwise. The default path never needs a browser.
+
+## Layer
+
+Foundation. `hugpy_tools` imports no other `hugpy_*` package. The `search`
+subpackage is owned by a separate work-stream.

hugpy_tools-0.2.2/pyproject.toml

@@ -0,0 +1,65 @@
+[build-system]
+requires = ["setuptools>=77", "setuptools-scm>=8"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "hugpy-tools"
+dynamic = ["version"]
+description = "Hugpy tools: a slim, stdlib-only capability suite for autonomous agents (safe file/path ops, text chunking and diffing, hashing, structured-data read/write, and urllib+html.parser webpage assessment)"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "LicenseRef-Proprietary"
+license-files = ["LICENSE"]
+authors = [{ name = "putkoff", email = "support@hugpy.ai" }]
+keywords = [
+    "hugpy",
+    "agent",
+    "tools",
+    "filesystem",
+    "webpage",
+    "assessment",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Topic :: Software Development :: Libraries",
+]
+# Deliberately dependency-free: stdlib only, so a machine with just Python can
+# use it and no other hugpy_* package is imported (foundation layer).
+dependencies = []
+
+[project.urls]
+Homepage = "https://hugpy.ai"
+Documentation = "https://github.com/hugpy/hugpy/blob/main/py/foundation/hugpy_tools/README.md"
+Repository = "https://github.com/hugpy/hugpy"
+Source = "https://github.com/hugpy/hugpy/tree/main/py/foundation/hugpy_tools"
+Issues = "https://github.com/hugpy/hugpy/issues"
+Changelog = "https://github.com/hugpy/hugpy/releases"
+Architecture = "https://github.com/hugpy/hugpy/blob/main/PARTITION.md"
+
+[project.optional-dependencies]
+# TOML reading uses stdlib tomllib on 3.11+; on 3.10 install the backport.
+toml = ["tomli; python_version < '3.11'"]
+# YAML reading is opt-in; the default never imports it.
+yaml = ["PyYAML"]
+# assess_webpage(force_render=True) can drive a headless browser if present.
+render = ["playwright"]
+test = ["pytest>=8", "pytest-timeout"]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+hugpy_tools = ["py.typed", "**/*.json", "**/*.md", "**/*.txt"]
+
+# ---------------------------------------------------------------------------
+# Lockstep workspace version (2026-09-22): every in-tree hugpy-* distribution
+# takes ONE version from the workspace git tag (vX.Y.Z at the repo root). A
+# checkout without git metadata builds as 0.0.0+unknown, which central refuses
+# to advertise to workers. (Identical policy to every sibling package.)
+[tool.setuptools_scm]
+root = "../../.."
+fallback_version = "0.0.0+unknown"

hugpy_tools-0.2.2/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

hugpy_tools-0.2.2/src/hugpy_tools/__init__.py

@@ -0,0 +1,84 @@
+"""hugpy-tools: a slim, stdlib-only capability suite for autonomous agents.
+
+Extracted from the sprawl of ``abstract_utilities`` / ``abstract_webtools`` and
+rebuilt with no third-party runtime dependency, so a machine with only Python
+can use it. It imports NO other ``hugpy_*`` package (foundation layer).
+
+Modules:
+
+    paths     path confinement (jail) + path-part helpers + filename sanitising
+    fs        safe file/dir ops: encoding-detecting read, line-range read,
+              atomic write, exact-string edit, list/tree, rich file info
+    hashkit   sha256 (text/file, streamed) + a cheap size+head quick hash
+    text      approximate token counting, token/line chunking, unified diffs
+    data      JSON/TOML/YAML read + atomic JSON write (safe dumping)
+    timekit   UTC ISO / epoch conversions
+    web       assess_webpage / prescreen_webpage — assessManager-parity webpage
+              assessment over urllib + html.parser (opt-in JS render)
+    search    reserved namespace (owned elsewhere; not implemented here)
+
+Every ``fs`` function takes an already-confined absolute path — call
+``paths.confine(root, path)`` first to enforce a jail. The web fetch never
+follows a redirect off http(s) and disables ``file://`` / ``ftp://``.
+"""
+from __future__ import annotations
+
+from hugpy_tools.data import read_data, safe_json_dumps, write_json
+from hugpy_tools.fs import (
+    atomic_write,
+    detect_encoding,
+    edit_replace,
+    file_info,
+    list_dir,
+    read_lines,
+    read_text,
+    tree,
+)
+from hugpy_tools.hashkit import quick_hash, sha256_file, sha256_text
+from hugpy_tools.paths import PathEscape, confine, file_parts, sanitize_filename
+from hugpy_tools.text import (
+    chunk_by_lines,
+    chunk_by_tokens,
+    count_tokens,
+    unified_diff,
+)
+from hugpy_tools.timekit import epoch_to_iso, iso_to_epoch, now_epoch, now_iso
+from hugpy_tools.web import assess_webpage, prescreen_webpage
+
+__all__ = [
+    # paths
+    "PathEscape",
+    "confine",
+    "file_parts",
+    "sanitize_filename",
+    # fs
+    "atomic_write",
+    "detect_encoding",
+    "edit_replace",
+    "file_info",
+    "list_dir",
+    "read_lines",
+    "read_text",
+    "tree",
+    # hashkit
+    "quick_hash",
+    "sha256_file",
+    "sha256_text",
+    # text
+    "chunk_by_lines",
+    "chunk_by_tokens",
+    "count_tokens",
+    "unified_diff",
+    # data
+    "read_data",
+    "safe_json_dumps",
+    "write_json",
+    # timekit
+    "epoch_to_iso",
+    "iso_to_epoch",
+    "now_epoch",
+    "now_iso",
+    # web
+    "assess_webpage",
+    "prescreen_webpage",
+]

hugpy_tools-0.2.2/src/hugpy_tools/data.py

@@ -0,0 +1,74 @@
+"""Structured-data read/write: JSON always, TOML via stdlib ``tomllib``, YAML
+only when PyYAML happens to be installed. Writing is JSON-only on purpose
+(stdlib has no TOML/YAML serializer); the write path is atomic.
+
+Every format degrades honestly: an unavailable parser raises a clear error
+naming exactly what is missing, never a silent wrong-format guess. Ported in
+spirit from abstract_utilities.json_utils (safe_dump / safe_read) but slimmed
+to the two calls an agent needs.
+"""
+from __future__ import annotations
+
+import json
+import os
+
+from . import fs
+
+# Map a lowercase extension to a logical format.
+_EXT_FORMAT = {
+    ".json": "json",
+    ".toml": "toml",
+    ".yaml": "yaml",
+    ".yml": "yaml",
+}
+
+
+def _format_for(path: str, explicit: str | None) -> str:
+    if explicit:
+        return explicit.lower()
+    return _EXT_FORMAT.get(os.path.splitext(path)[1].lower(), "json")
+
+
+def read_data(path: str, fmt: str | None = None):
+    """Parse a JSON/TOML/YAML file to a Python object. Format is inferred from
+    the extension unless ``fmt`` is given. Raises ``RuntimeError`` when a
+    parser is unavailable, ``ValueError`` on an unknown format."""
+    fmt = _format_for(path, fmt)
+    if fmt == "json":
+        with open(path, "rb") as fh:
+            return json.loads(fh.read().decode("utf-8", errors="replace"))
+    if fmt == "toml":
+        try:
+            import tomllib  # stdlib >= 3.11
+        except ModuleNotFoundError as exc:
+            raise RuntimeError(
+                "TOML reading needs Python 3.11+ (stdlib 'tomllib'); this "
+                "interpreter is older. Install the 'tomli' backport and read "
+                "it yourself, or upgrade Python.") from exc
+        with open(path, "rb") as fh:
+            return tomllib.load(fh)
+    if fmt == "yaml":
+        try:
+            import yaml  # optional third-party
+        except ModuleNotFoundError as exc:
+            raise RuntimeError(
+                "YAML reading needs PyYAML, which is not installed "
+                "(hugpy_tools is stdlib-only). Install 'PyYAML' to enable "
+                "YAML.") from exc
+        with open(path, "rb") as fh:
+            return yaml.safe_load(fh)
+    raise ValueError("unknown data format %r (use json/toml/yaml)" % fmt)
+
+
+def safe_json_dumps(obj, indent: int = 2, sort_keys: bool = False) -> str:
+    """``json.dumps`` that never explodes on a non-serialisable value: anything
+    the encoder cannot handle is stringified via ``default=str`` and non-ASCII
+    is preserved (``ensure_ascii=False``)."""
+    return json.dumps(obj, indent=indent, sort_keys=sort_keys,
+                      ensure_ascii=False, default=str)
+
+
+def write_json(path: str, obj, indent: int = 2, sort_keys: bool = False) -> dict:
+    """Serialise ``obj`` to JSON and write it atomically. Returns
+    ``{path, bytes, mode}`` (from :func:`fs.atomic_write`)."""
+    return fs.atomic_write(path, safe_json_dumps(obj, indent, sort_keys) + "\n")

hugpy_tools-0.2.2/src/hugpy_tools/fs.py

@@ -0,0 +1,231 @@
+"""Safe file/directory operations (stdlib only).
+
+Every function here takes an ALREADY-CONFINED absolute path — confinement is
+the caller's job (see :func:`paths.confine`). That split keeps this module a
+pure file-ops library with no policy of its own, which is exactly what a
+standalone package wants.
+
+Highlights ported from abstract_utilities:
+  * encoding detection on read (BOM sniff -> utf-8 -> cp1252 fallback)
+  * atomic write (temp file in the same dir + ``os.replace``)
+  * exact string edit with an occurrence-count contract
+  * directory listing + bounded recursive tree + rich file info
+"""
+from __future__ import annotations
+
+import os
+import tempfile
+from datetime import datetime, timezone
+
+from . import hashkit
+
+# BOM -> declared encoding
+_BOMS = (
+    (b"\xef\xbb\xbf", "utf-8-sig"),
+    (b"\xff\xfe\x00\x00", "utf-32-le"),
+    (b"\x00\x00\xfe\xff", "utf-32-be"),
+    (b"\xff\xfe", "utf-16-le"),
+    (b"\xfe\xff", "utf-16-be"),
+)
+
+
+def detect_encoding(data: bytes) -> str:
+    """Best-effort encoding guess for ``data`` using only stdlib: honour a BOM,
+    then prefer strict utf-8, then fall back to cp1252 (a superset of latin-1
+    that decodes any byte). Never raises."""
+    for bom, enc in _BOMS:
+        if data.startswith(bom):
+            return enc
+    try:
+        data.decode("utf-8")
+        return "utf-8"
+    except UnicodeDecodeError:
+        return "cp1252"
+
+
+def read_text(path: str, max_bytes: int | None = None) -> dict:
+    """Read a text file with encoding detection. Returns
+    ``{path, encoding, bytes, truncated, text}``."""
+    with open(path, "rb") as fh:
+        if max_bytes is None:
+            raw = fh.read()
+            truncated = False
+        else:
+            raw = fh.read(max_bytes + 1)
+            truncated = len(raw) > max_bytes
+            raw = raw[:max_bytes]
+    enc = detect_encoding(raw)
+    return {
+        "path": path,
+        "encoding": enc,
+        "bytes": len(raw),
+        "truncated": truncated,
+        "text": raw.decode(enc, errors="replace"),
+    }
+
+
+def read_lines(path: str, start: int = 1, end: int | None = None,
+               number: bool = False) -> dict:
+    """Read a 1-based inclusive line range. ``end=None`` reads to EOF.
+    Returns ``{path, start, end, total_lines, returned, text}``."""
+    start = max(1, int(start))
+    with open(path, "rb") as fh:
+        raw = fh.read()
+    enc = detect_encoding(raw)
+    lines = raw.decode(enc, errors="replace").splitlines()
+    total = len(lines)
+    last = total if end is None else min(int(end), total)
+    chosen = lines[start - 1:last] if start <= total else []
+    if number:
+        width = len(str(last))
+        body = "\n".join("%*d\t%s" % (width, start + i, ln)
+                         for i, ln in enumerate(chosen))
+    else:
+        body = "\n".join(chosen)
+    return {
+        "path": path,
+        "start": start,
+        "end": last,
+        "total_lines": total,
+        "returned": len(chosen),
+        "text": body,
+    }
+
+
+def atomic_write(path: str, content: str, append: bool = False,
+                 encoding: str = "utf-8") -> dict:
+    """Write ``content`` durably. Overwrite is atomic (temp file in the same
+    directory + ``os.replace``, so a reader never sees a half-written file).
+    Append opens the real file directly (append has no atomic swap). Returns
+    ``{path, bytes, mode}``."""
+    os.makedirs(os.path.dirname(path) or ".", exist_ok=True)
+    data = content.encode(encoding, errors="replace")
+    if append:
+        with open(path, "ab") as fh:
+            fh.write(data)
+    else:
+        directory = os.path.dirname(path) or "."
+        fd, tmp = tempfile.mkstemp(dir=directory, prefix=".tmp-", suffix=".part")
+        try:
+            with os.fdopen(fd, "wb") as fh:
+                fh.write(data)
+            os.replace(tmp, path)
+        except BaseException:
+            try:
+                os.unlink(tmp)
+            except OSError:
+                pass
+            raise
+    return {"path": path, "bytes": len(data),
+            "mode": "append" if append else "overwrite"}
+
+
+def edit_replace(path: str, old: str, new: str, count: int | None = None) -> dict:
+    """Exact string replacement in a text file. By default every occurrence is
+    replaced; pass ``count`` to bound it. Raises ``ValueError`` if ``old`` is
+    empty or not found. Returns ``{path, replaced, bytes}``; the write is
+    atomic."""
+    if old == "":
+        raise ValueError("old must be a non-empty string")
+    info = read_text(path)
+    text = info["text"]
+    occurrences = text.count(old)
+    if occurrences == 0:
+        raise ValueError("old string not found in %s" % path)
+    replaced = occurrences if count is None else min(occurrences, int(count))
+    text = text.replace(old, new, -1 if count is None else int(count))
+    out = atomic_write(path, text, encoding="utf-8"
+                       if info["encoding"] in ("utf-8", "utf-8-sig", "cp1252")
+                       else info["encoding"])
+    return {"path": path, "replaced": replaced, "bytes": out["bytes"]}
+
+
+def _iso(ts: float) -> str:
+    return datetime.fromtimestamp(ts, tz=timezone.utc).isoformat()
+
+
+def file_info(path: str, hash_files: bool = False) -> dict:
+    """Rich stat for one path. For a regular file with ``hash_files`` the
+    sha256 is included."""
+    st = os.lstat(path)
+    is_link = os.path.islink(path)
+    real = os.path.realpath(path)
+    is_dir = os.path.isdir(real)
+    info = {
+        "path": path,
+        "name": os.path.basename(path.rstrip(os.sep)) or path,
+        "type": "dir" if is_dir else ("symlink" if is_link and not os.path.exists(real) else "file"),
+        "is_dir": is_dir,
+        "is_symlink": is_link,
+        "size": st.st_size,
+        "mtime": _iso(st.st_mtime),
+    }
+    if hash_files and not is_dir and os.path.isfile(real):
+        info["sha256"] = hashkit.sha256_file(real)
+    return info
+
+
+def list_dir(path: str, glob: str | None = None, files_only: bool = False,
+             dirs_only: bool = False, limit: int = 500) -> dict:
+    """List the immediate entries of a directory (sorted: dirs first, then
+    files, each alphabetical). Optional fnmatch ``glob`` on the entry name.
+    Returns ``{path, count, truncated, entries:[{name,type,size,mtime}]}``."""
+    import fnmatch
+    names = sorted(os.listdir(path))
+    entries = []
+    for name in names:
+        full = os.path.join(path, name)
+        is_dir = os.path.isdir(full)
+        if files_only and is_dir:
+            continue
+        if dirs_only and not is_dir:
+            continue
+        if glob and not fnmatch.fnmatch(name, glob):
+            continue
+        try:
+            st = os.lstat(full)
+            size, mtime = st.st_size, _iso(st.st_mtime)
+        except OSError:
+            size, mtime = None, None
+        entries.append({"name": name,
+                        "type": "dir" if is_dir else "file",
+                        "size": size, "mtime": mtime})
+    entries.sort(key=lambda e: (e["type"] != "dir", e["name"]))
+    truncated = len(entries) > limit
+    return {"path": path, "count": len(entries), "truncated": truncated,
+            "entries": entries[:limit]}
+
+
+def tree(path: str, max_depth: int = 3, max_entries: int = 500,
+         show_files: bool = True) -> dict:
+    """Bounded recursive directory tree rendered as indented text. Skips
+    symlinked directories (never recurses out through a link). Returns
+    ``{path, entries, truncated, text}`` where ``entries`` is the count
+    emitted."""
+    lines: list[str] = []
+    state = {"n": 0, "truncated": False}
+
+    def walk(cur: str, depth: int, prefix: str) -> None:
+        if depth > max_depth or state["truncated"]:
+            return
+        try:
+            names = sorted(os.listdir(cur))
+        except OSError:
+            return
+        dirs = [n for n in names if os.path.isdir(os.path.join(cur, n))
+                and not os.path.islink(os.path.join(cur, n))]
+        files = [n for n in names if not os.path.isdir(os.path.join(cur, n))]
+        ordered = [(n, True) for n in dirs] + \
+                  ([(n, False) for n in files] if show_files else [])
+        for name, is_dir in ordered:
+            if state["n"] >= max_entries:
+                state["truncated"] = True
+                return
+            state["n"] += 1
+            lines.append("%s%s%s" % (prefix, name, "/" if is_dir else ""))
+            if is_dir:
+                walk(os.path.join(cur, name), depth + 1, prefix + "  ")
+
+    walk(path, 1, "")
+    return {"path": path, "entries": state["n"],
+            "truncated": state["truncated"], "text": "\n".join(lines)}