millforge 0.1.0__py3-none-any.whl

millforge/tools/path_policy.py

@@ -0,0 +1,155 @@
+"""Contained logical path policy for built-in runtime tools."""
+
+from __future__ import annotations
+
+import os
+import re
+import tempfile
+from pathlib import Path, PurePosixPath
+
+_WINDOWS_DRIVE_RE = re.compile(r"^[a-zA-Z]:")
+_WINDOWS_DEVICE_PREFIXES = ("\\\\?\\", "\\\\.\\", "//?/", "//./")
+_UNC_PREFIXES = ("\\\\", "//")
+_WINDOWS_RESERVED_DEVICE_NAMES = frozenset(
+    {
+        "aux",
+        "con",
+        "conin$",
+        "conout$",
+        "nul",
+        "prn",
+        *{f"com{i}" for i in range(1, 10)},
+        *{f"lpt{i}" for i in range(1, 10)},
+    }
+)
+
+
+class PathPolicyError(ValueError):
+    """Raised when a model-provided logical path is outside policy."""
+
+
+def validate_logical_path(value: str, *, allow_dot: bool = False) -> PurePosixPath:
+    """Validate a model-visible logical path before host resolution."""
+    if not isinstance(value, str) or not value.strip():
+        raise PathPolicyError("path must be a non-empty logical relative path")
+    if "\x00" in value:
+        raise PathPolicyError("path contains a NUL byte")
+    if "\\" in value:
+        raise PathPolicyError("path must use POSIX separators")
+    if ":" in value:
+        raise PathPolicyError("path must not contain Windows drive or ADS syntax")
+    if value.startswith(_WINDOWS_DEVICE_PREFIXES) or value.startswith(_UNC_PREFIXES):
+        raise PathPolicyError("path must not use Windows device or UNC syntax")
+    if _WINDOWS_DRIVE_RE.match(value):
+        raise PathPolicyError("path must not use a Windows drive prefix")
+    path = PurePosixPath(value)
+    if path.is_absolute() or value.startswith("/"):
+        raise PathPolicyError("path must not be absolute")
+    if value.startswith("~"):
+        raise PathPolicyError("path must not use home-directory syntax")
+    parts = path.parts
+    if any(part in ("", "..") for part in parts):
+        raise PathPolicyError("path must not contain traversal components")
+    if not allow_dot and any(part == "." for part in parts):
+        raise PathPolicyError("path must not contain current-directory components")
+    if parts == (".",) and not allow_dot:
+        raise PathPolicyError("path must not be current directory")
+    _reject_windows_reserved_device_names(parts)
+    return path
+
+
+def resolve_existing_contained(
+    root: Path, logical: str, *, allow_dot: bool = False
+) -> Path:
+    """Resolve an existing logical path under a trusted root."""
+    path = validate_logical_path(logical, allow_dot=allow_dot)
+    root_resolved = root.resolve(strict=True)
+    candidate = (root_resolved / Path(*path.parts)).resolve(strict=True)
+    _ensure_contained(root_resolved, candidate)
+    return candidate
+
+
+def resolve_write_contained(root: Path, logical: str) -> Path:
+    """Resolve a writable logical file path under a trusted root."""
+    path = validate_logical_path(logical)
+    root_resolved = root.resolve(strict=True)
+    candidate = root_resolved / Path(*path.parts)
+    parent = candidate.parent.resolve(strict=True)
+    _ensure_contained(root_resolved, parent)
+    if candidate.exists() or candidate.is_symlink():
+        resolved = candidate.resolve(strict=True)
+        _ensure_contained(root_resolved, resolved)
+        if resolved.is_dir():
+            raise PathPolicyError("path resolves to a directory")
+        return resolved
+    return parent / candidate.name
+
+
+def atomic_write_contained(root: Path, logical: str, content: bytes) -> str:
+    """Atomically write bytes to a contained logical path and return sha256."""
+    target = resolve_write_contained(root, logical)
+    digest = canonical_sha256_bytes(content)
+    fd: int | None = None
+    tmp_path: str | None = None
+    try:
+        fd, tmp_path = tempfile.mkstemp(
+            dir=str(target.parent),
+            prefix=f".{target.name}.tmp.",
+        )
+        with os.fdopen(fd, "wb") as handle:
+            fd = None
+            handle.write(content)
+            handle.flush()
+            os.fsync(handle.fileno())
+        os.replace(tmp_path, target)
+        tmp_path = None
+    finally:
+        if fd is not None:
+            try:
+                os.close(fd)
+            except OSError:
+                pass
+        if tmp_path is not None:
+            try:
+                os.unlink(tmp_path)
+            except OSError:
+                pass
+    return digest
+
+
+def canonical_sha256_bytes(content: bytes) -> str:
+    """Hash raw bytes using the same lowercase SHA-256 format as JSON results."""
+    import hashlib
+
+    return hashlib.sha256(content).hexdigest()
+
+
+def logical_from_resolved(root: Path, target: Path) -> str:
+    """Return a POSIX logical path after containment has already been enforced."""
+    root_resolved = root.resolve(strict=True)
+    resolved = target.resolve(strict=True)
+    _ensure_contained(root_resolved, resolved)
+    return resolved.relative_to(root_resolved).as_posix()
+
+
+def _ensure_contained(root: Path, candidate: Path) -> None:
+    try:
+        candidate.relative_to(root)
+    except ValueError as exc:
+        raise PathPolicyError("path resolves outside the trusted root") from exc
+
+
+def _reject_windows_reserved_device_names(parts: tuple[str, ...]) -> None:
+    for part in parts:
+        if part in (".", ".."):
+            continue
+        if _is_windows_reserved_device_name(part):
+            raise PathPolicyError("path must not use a reserved Windows device name")
+
+
+def _is_windows_reserved_device_name(part: str) -> bool:
+    trimmed = part.rstrip(" .")
+    if not trimmed:
+        return False
+    base = trimmed.split(".", 1)[0].rstrip(" .").casefold()
+    return base in _WINDOWS_RESERVED_DEVICE_NAMES

millforge/tools/pi_compat/PI_LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Mario Zechner
+
+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.

millforge/tools/pi_compat/PROVENANCE.json

@@ -0,0 +1,55 @@
+{
+  "schema_version": 1,
+  "upstream": {
+    "repository": "https://github.com/earendil-works/pi",
+    "package": "@earendil-works/pi-coding-agent",
+    "version": "0.79.6",
+    "license": "MIT",
+    "copyright": "Copyright (c) 2025 Mario Zechner"
+  },
+  "source_snapshot": "reference/pi/",
+  "source_history": "The approved reference copy is history-free. No upstream commit hash is recorded or inferred.",
+  "adaptations": [
+    "Python filesystem and process APIs replace Node APIs.",
+    "`pathspec` and the exact Section 7 ignore rules replace `fd`/`rg` discovery.",
+    "Python regex/glob, binary detection, decoding, traversal, and error rules are the exact Section 7 search adaptation.",
+    "supported image reads return the exact successful text-only result in Spec 11 Section 6 instead of multimodal image content; non-image bytes retain Pi's UTF-8 replacement-decoding behavior.",
+    "the poll/wait cancellation protocol replaces Pi's abort signal.",
+    "Windows uses COMSPEC/cmd.exe while POSIX preserves Pi's Bash-first order.",
+    "the inherited environment omits Pi's private bin-directory PATH mutation.",
+    "the 11A-owned async timer enforces the caller-supplied strictly positive finite timeout; expiry after spawn performs the specified process-tree cleanup and returns `process_timeout` with `completion_unknown`."
+  ],
+  "pinned_paths": [
+    {"path": "LICENSE", "sha256": "0457f5bcec3b3b211605dfb5d1a49042fd638f3686a410fe099c24a25af13c48", "classification": "ported"},
+    {"path": "packages/coding-agent/package.json", "sha256": "76919365cc55f94e79a27583ec2f36c917c0312e529f6b83f71c7817b6774f55", "classification": "excluded"},
+    {"path": "packages/coding-agent/src/core/tools/index.ts", "sha256": "afeb406e0f5edde143aaac51b9c928cb497bfb8216c04ac9242bfd0f9241ffe1", "classification": "adapted"},
+    {"path": "packages/coding-agent/src/core/tools/read.ts", "sha256": "954419870e12b9e82e45a37bd3f9e6dda5bd80aa44ea56fbcdac0f976676d03e", "classification": "adapted"},
+    {"path": "packages/coding-agent/src/core/tools/ls.ts", "sha256": "0cd36018b68f08c98e615c761d6c3af19842537cd500d7be9912f932cd2b1b22", "classification": "ported"},
+    {"path": "packages/coding-agent/src/core/tools/grep.ts", "sha256": "9737dcfd27ae56a33fd934c0b336b9f1cb64eaab6b6378a91270dde4b505ba47", "classification": "adapted"},
+    {"path": "packages/coding-agent/src/core/tools/find.ts", "sha256": "f6f2d780df007af22d67101dc17ffae7c9d670893be168628eeebb01345b97df", "classification": "adapted"},
+    {"path": "packages/coding-agent/src/core/tools/write.ts", "sha256": "7f7f1425e2a7cdffe48b190033189fd03dffc5756708b12775dddb0acfe90c6c", "classification": "ported"},
+    {"path": "packages/coding-agent/src/core/tools/edit.ts", "sha256": "373083e70b8f58dc49b213a4046e4095e1acc5fb0bea1925185e09e0d3c00618", "classification": "ported"},
+    {"path": "packages/coding-agent/src/core/tools/edit-diff.ts", "sha256": "b76fab8a2868b1e65970286928e996e76918ba8b8dbfdefe9ab0fe34420f9c90", "classification": "ported"},
+    {"path": "packages/coding-agent/src/core/tools/bash.ts", "sha256": "9d932837466dee1f8fd84cae3b180363aa523118ff8c84a992eeab18dcd3be29", "classification": "adapted"},
+    {"path": "packages/coding-agent/src/core/tools/truncate.ts", "sha256": "104e61ea602c7f7894097b2771dad8c68de75c5a10ea6222e615c4ad144451c7", "classification": "ported"},
+    {"path": "packages/coding-agent/src/core/tools/output-accumulator.ts", "sha256": "c601ddd8e10934be6f3db30696eacba7b9544f2dd1648a5ec3c9935f0d4625c3", "classification": "adapted"},
+    {"path": "packages/coding-agent/src/core/tools/path-utils.ts", "sha256": "ab6f420d2388a41366113c17a25e356867820b87b02a169d044cfcf83e1997d3", "classification": "ported"},
+    {"path": "packages/coding-agent/src/core/tools/file-mutation-queue.ts", "sha256": "33cb06ac9bcdf32c8b84d9d12e33be44c503a7670f668e003a3262cd34294d11", "classification": "adapted"},
+    {"path": "packages/coding-agent/src/core/tools/render-utils.ts", "sha256": "38913e15575b7c314687c1a7d53b2763eecb8e7a86b0b58d7b5532c900503cf3", "classification": "excluded"},
+    {"path": "packages/coding-agent/src/utils/shell.ts", "sha256": "7a74bb1f3809fa62771827a9c814636b9742760f6deddc517a84ae237dc4fbef", "classification": "adapted"},
+    {"path": "packages/coding-agent/src/utils/child-process.ts", "sha256": "cd324f5b9a1abadd85ab5a331750d475c8bd51ec65cae091ad9b416245ec85d4", "classification": "adapted"},
+    {"path": "packages/coding-agent/src/utils/mime.ts", "sha256": "b562303ba7bbf27432bd310891fe656a8473995a4a1f8ba2e00a79b56400605c", "classification": "ported"},
+    {"path": "packages/coding-agent/src/utils/paths.ts", "sha256": "c433bd9f98744aa9a373282fd50ab3657b6e2a366feecbfb177fe648746d1944", "classification": "ported"},
+    {"path": "packages/coding-agent/test/tools.test.ts", "sha256": "0360d773cfef2e08f23490b9c83d4bb5b88ce070bf79c57d227c5fd2fcd121e9", "classification": "test-derived"},
+    {"path": "packages/coding-agent/test/path-utils.test.ts", "sha256": "08bb88574596a43e2364ee3b2655e071593822417ef8937693744174e9615f3e", "classification": "test-derived"},
+    {"path": "packages/coding-agent/test/bash-close-hang-windows.test.ts", "sha256": "1d2230b25129a365cbae417269b65c1724772104328f584ee521cb5c255b49fb", "classification": "test-derived"},
+    {"path": "packages/coding-agent/test/suite/regressions/3302-find-path-glob.test.ts", "sha256": "d8816a5ed1f3033439e7866dc9c7b87b7e7a265caf186bae3817443b597e1d02", "classification": "test-derived"},
+    {"path": "packages/coding-agent/test/suite/regressions/3303-find-nested-gitignore.test.ts", "sha256": "bcc7517366d11bf9cc3b8dade9d54bfbe6cd482a23deb9d6d966d1b2e09c6982", "classification": "test-derived"},
+    {"path": "packages/coding-agent/test/suite/regressions/5208-late-bash-output.test.ts", "sha256": "9d6fc0d457e6d7470246d821deec9937d428e86fdad6858d05e7d5c956802f8c", "classification": "test-derived"},
+    {"path": "packages/coding-agent/test/suite/regressions/5303-bash-output-truncation.test.ts", "sha256": "d690fdad5de2bd82f016892972395d49d3b83570d5223f4f473626d34af10136", "classification": "test-derived"},
+    {"path": "packages/coding-agent/src/core/system-prompt.ts", "sha256": "49cd7166a7f1eb8d088b7d8b8f2c38642de827ac2ff7a327ec4b7549b543d8d1", "classification": "adapted"},
+    {"path": "packages/coding-agent/src/core/resource-loader.ts", "sha256": "9e339467f3c5997ec363ad96ff18e1850cff71e2ab37dfeca7b4e8782926a2ff", "classification": "adapted"},
+    {"path": "packages/coding-agent/test/system-prompt.test.ts", "sha256": "6443dbc77ee1c39ca14c89652079e0907f47a4efae2bf9ce08323442983e2981", "classification": "test-derived"},
+    {"path": "packages/coding-agent/test/resource-loader.test.ts", "sha256": "98b343646e389f87743ef548f9c23e329ccf1eb0bb6945a66016884ec515b45e", "classification": "test-derived"}
+  ]
+}

millforge/tools/pi_compat/UPDATE_POLICY.md

@@ -0,0 +1,36 @@
+# Pi Compatibility Update Policy
+
+This source-attributed behavioral port may be updated only as an isolated,
+reviewable change against a new approved Pi snapshot.
+
+1. Record the upstream package name, version, license, repository URL, and
+   approved snapshot location. Do not invent a commit hash when the snapshot
+   has no history.
+2. Recompute SHA-256 values for every path in PROVENANCE.json before copying
+   or translating behavior. Stop the update when a pinned source differs until
+   the source version and manifest are explicitly reconciled.
+3. Review Pi's tool sources, utility sources, and source-derived tests together.
+   Preserve model-visible text unless a documented Spec 11 adaptation requires
+   a divergence.
+4. Reassess the complete adaptation list, including Python filesystem/process
+   APIs, text-only image results, search implementation, mutation locking, and
+   Windows shell behavior. Document any newly required divergence in the
+   accepted specification, provenance, tests, and public documentation.
+5. Copy the upstream MIT notice unmodified, update every path hash and
+   classification, and keep the package-data rules in sync.
+6. Run the source-derived focused tests, the full relevant Millforge tests,
+   Ruff, MyPy, dependency checks, and package-content verification before
+   accepting the update.
+
+No Pi runtime, Node package, downloaded search binary, or unreviewed source
+snapshot is an acceptable substitute for this procedure.
+
+## Current Platform Validation
+
+The POSIX shell path, timeout, cancellation, process-group cleanup, output
+ordering, and persistence behavior are covered by the bundled Python 3.12
+tests. The Windows `COMSPEC`/`cmd.exe` and `taskkill /F /T` implementation is
+source-reviewed and has platform-gated contract tests, but native Windows
+process-tree stress behavior was not locally verified for the 0.79.6 port.
+Run those gated tests in a controlled Windows CI environment before claiming
+native Windows process-tree parity.

millforge/tools/pi_compat/__init__.py

@@ -0,0 +1,34 @@
+"""Source-attributed Pi 0.79.6 coding-tool compatibility operations."""
+
+from .contracts import (
+    PiCompatErrorKind,
+    PiCompatOperationResult,
+    PiCompatSideEffectState,
+)
+from .editing import execute_edit
+from .operations import execute_ls, execute_read, execute_write
+from .process import (
+    PiCompatCancellation,
+    PiCompatShellConfig,
+    PiCompatShellResolutionError,
+    execute_bash,
+    resolve_pi_compat_shell,
+)
+from .search import execute_find, execute_grep
+
+__all__ = [
+    "PiCompatCancellation",
+    "PiCompatErrorKind",
+    "PiCompatOperationResult",
+    "PiCompatShellConfig",
+    "PiCompatShellResolutionError",
+    "PiCompatSideEffectState",
+    "execute_bash",
+    "execute_edit",
+    "execute_find",
+    "execute_grep",
+    "execute_ls",
+    "execute_read",
+    "execute_write",
+    "resolve_pi_compat_shell",
+]

millforge/tools/pi_compat/contracts.py

@@ -0,0 +1,49 @@
+"""Shared contracts for the Pi 0.79.6 compatibility operation pack."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import Enum
+from pathlib import Path
+
+__all__ = [
+    "PiCompatErrorKind",
+    "PiCompatOperationResult",
+    "PiCompatSideEffectState",
+]
+
+
+class PiCompatErrorKind(str, Enum):
+    """Closed operation errors translated by the unrestricted tool adapter."""
+
+    INVALID_ARGUMENTS = "invalid_arguments"
+    NOT_FOUND = "not_found"
+    PERMISSION_DENIED = "permission_denied"
+    CONFLICT = "conflict"
+    IO_ERROR = "io_error"
+    PROCESS_EXIT_NONZERO = "process_exit_nonzero"
+    PROCESS_TIMEOUT = "process_timeout"
+    CANCELLED = "cancelled"
+    PROCESS_LAUNCH_ERROR = "process_launch_error"
+
+
+class PiCompatSideEffectState(str, Enum):
+    """The operation's explicit side-effect certainty."""
+
+    NOT_ATTEMPTED = "not_attempted"
+    CONFIRMED_ABSENT = "confirmed_absent"
+    CONFIRMED_COMPLETE = "confirmed_complete"
+    ROLLED_BACK = "rolled_back"
+    COMPLETION_UNKNOWN = "completion_unknown"
+
+
+@dataclass(frozen=True)
+class PiCompatOperationResult:
+    """The complete model-visible result of one Pi-compatible operation."""
+
+    model_text: str
+    truncated: bool
+    error_kind: PiCompatErrorKind | None
+    exit_code: int | None
+    changed_path: Path | None
+    side_effect_state: PiCompatSideEffectState