vidbyte-cli 0.1.0__py3-none-any.whl

vidbyte_cli/lib/errors/handler.py

@@ -0,0 +1,72 @@
+"""The single boundary where an exception becomes safe output and a process status.
+
+One match statement classifies everything that can reach `CliApplication.run`, so the set of
+exception kinds the CLI understands is readable in one place. Anything unmatched is a CLI
+defect, not a user mistake, and is reported without quoting the exception value — a foreign
+exception string may hold a credential, a prompt, or a backend response body.
+
+Debug mode adds stack frames only. Never locals, never exception values, never causes.
+"""
+
+from __future__ import annotations
+
+import traceback
+
+import click
+
+from ..output.manager import OutputManager
+from .cli_error import CliError
+from .codes import ExitCode
+from .failures import InvalidCommandUsage, OperationInterrupted, UnexpectedInternalError
+
+
+class ErrorHandler:
+    """Central conversion from boundary exceptions to safe CLI failures."""
+
+    def __init__(self, output: OutputManager, debug: bool = False) -> None:
+        self._output = output
+        self._debug = debug
+
+    def handle(self, error: BaseException) -> int:
+        # UsageError precedes ClickException because it is the more specific subclass.
+        match error:
+            case BrokenPipeError():
+                # A closed downstream pipe is a normal shell outcome, not a failure.
+                return int(ExitCode.SUCCESS)
+            case CliError():
+                return self._report(error, error)
+            case click.UsageError():
+                context = error.ctx
+                path = context.command_path if context is not None else "vidbyte-cli"
+                return self._report(
+                    InvalidCommandUsage(error.format_message(), path, error.exit_code, error),
+                    error,
+                )
+            case click.ClickException():
+                return self._report(
+                    InvalidCommandUsage(
+                        error.format_message(), "vidbyte-cli", error.exit_code, error
+                    ),
+                    error,
+                )
+            case click.exceptions.Abort() | KeyboardInterrupt():
+                return self._report(OperationInterrupted(), error)
+            case _:
+                cause = error if isinstance(error, Exception) else None
+                return self._report(UnexpectedInternalError(cause), error)
+
+    def _report(self, mapped: CliError, original: BaseException) -> int:
+        # Render once, then optionally add frames from whichever exception carries them.
+        self._output.error(mapped)
+        if self._debug:
+            self._render_redacted_trace(mapped.cause or original)
+        return mapped.exit_code
+
+    def _render_redacted_trace(self, error: BaseException) -> None:
+        # Format stack frames only; exception values and chained causes may hold secrets.
+        self._output.diagnostic("Debug traceback (exception values redacted):")
+        if error.__traceback__ is None:
+            self._output.diagnostic(f"  {type(error).__module__}.{type(error).__qualname__}")
+            return
+        for line in traceback.format_tb(error.__traceback__):
+            self._output.diagnostic(line.rstrip())

vidbyte_cli/lib/files/__init__.py

@@ -0,0 +1,6 @@
+"""Public local-file contract: stores rooted at one directory, product-neutral."""
+
+from .documents import LocalDocumentStore
+from .store import LocalFileStore
+
+__all__ = ["LocalDocumentStore", "LocalFileStore"]

vidbyte_cli/lib/files/documents.py

@@ -0,0 +1,94 @@
+"""Versioned JSON documents validated by a caller-supplied pydantic model.
+
+A command that keeps small structured records on disk — catalogs, indexes, per-item memory —
+reads and writes them here, so bounding, parsing, model validation, containment of linked
+names, and deterministic serialization are decided once. Bytes still move through
+`LocalFileStore`; which model a document uses and what its fields mean stay with the caller.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import TypeVar
+
+from pydantic import BaseModel, ValidationError
+
+from ..errors.failures import LocalDocumentInvalid, LocalFileReadFailed, LocalFileWriteFailed
+from .store import LocalFileStore
+
+DocumentT = TypeVar("DocumentT", bound=BaseModel)
+
+DEFAULT_MAX_DOCUMENT_BYTES = 1_000_000
+
+
+class LocalDocumentStore:
+    """Reads, validates, atomically writes, and removes JSON documents under one root."""
+
+    def __init__(self, root: Path, *, max_bytes: int = DEFAULT_MAX_DOCUMENT_BYTES) -> None:
+        # The byte cap is per store so a caller holding tiny indexes can refuse a runaway file
+        # before it is decoded, while the file store underneath keeps paths absolute.
+        self._files = LocalFileStore(root)
+        self._max_bytes = max_bytes
+
+    @property
+    def root(self) -> Path:
+        # The absolute directory every document name resolves against.
+        return self._files.root
+
+    def path_of(self, name: str | Path) -> Path:
+        # Names often come from another document (a catalog linking to a record), so a name
+        # that is absolute, climbs with `..`, or resolves outside the root through a link is
+        # refused rather than trusted.
+        relative = Path(name)
+        if relative.is_absolute() or ".." in relative.parts:
+            raise LocalDocumentInvalid(relative.name, "its name leaves the document directory")
+        candidate = self._files.path_of(relative).resolve()
+        if not candidate.is_relative_to(self.root):
+            raise LocalDocumentInvalid(relative.name, "its name leaves the document directory")
+        return candidate
+
+    def exists(self, name: str | Path) -> bool:
+        # Presence of a regular file or of a link at that name, since either would be replaced.
+        path = self.path_of(name)
+        return path.is_file() or path.is_symlink()
+
+    def read(self, name: str | Path, model: type[DocumentT]) -> DocumentT | None:
+        # None means absent and nothing else. A present document that is oversized, not JSON,
+        # or not an instance of the model raises, so broken state is never read as empty state.
+        path = self.path_of(name)
+        try:
+            size = path.stat().st_size
+        except FileNotFoundError:
+            return None
+        except OSError as error:
+            raise LocalFileReadFailed(path.name, LocalFileStore.reason_for(error), error) from error
+        if size > self._max_bytes:
+            raise LocalDocumentInvalid(path.name, f"it exceeds {self._max_bytes} bytes")
+        parsed = self._files.read_json(path)
+        if parsed is None:
+            return None
+        try:
+            return model.model_validate(parsed)
+        except ValidationError as error:
+            raise LocalDocumentInvalid(
+                path.name, f"it does not match the {model.__name__} schema", error
+            ) from error
+
+    def write(self, name: str | Path, document: BaseModel) -> Path:
+        # Sorted, indented, newline-terminated output keeps documents diffable by hand and
+        # byte-stable across runs; the file store replaces the target atomically.
+        path = self.path_of(name)
+        body = json.dumps(document.model_dump(mode="json"), indent=2, sort_keys=True) + "\n"
+        return self._files.write_text(path, body)
+
+    def remove(self, name: str | Path) -> None:
+        # Used to roll back a document written earlier in the same mutation; an already absent
+        # document is the desired end state, not a failure.
+        path = self.path_of(name)
+        try:
+            path.unlink(missing_ok=True)
+        except OSError as error:
+            raise LocalFileWriteFailed(
+                path.name, LocalFileStore.reason_for(error), error
+            ) from error

vidbyte_cli/lib/files/store.py

@@ -0,0 +1,156 @@
+"""Product-neutral file I/O behind one store rooted at one directory.
+
+Any command or runtime primitive that keeps local files — checkpoints, logs, reports,
+exported documents — reads and writes them through this class, so atomicity, encoding, and
+path resolution are decided once instead of at each call site. It knows paths and bytes only:
+which file a record belongs in, and what its contents mean, is always the caller's decision.
+Owner-only CLI state such as config and credentials goes through `lib/config/atomic.py`.
+"""
+
+from __future__ import annotations
+
+import errno
+import json
+import os
+import shutil
+import tempfile
+from pathlib import Path
+
+from ..errors.failures import LocalFileReadFailed, LocalFileWriteFailed
+
+
+class LocalFileStore:
+    """Resolves, reads, and atomically writes files under one root directory."""
+
+    def __init__(self, root: Path) -> None:
+        # Resolving once at construction is what makes every path this store returns absolute,
+        # so a file a result reports stays addressable from another working directory.
+        self._root = root.expanduser().resolve()
+
+    @property
+    def root(self) -> Path:
+        # The absolute directory every relative name in this store resolves against.
+        return self._root
+
+    def path_of(self, name: str | Path) -> Path:
+        # One join site. An absolute name passes through unchanged, which is how a caller
+        # writes a destination it was handed without building a second store for it.
+        return self._root / name
+
+    def exists(self, name: str | Path) -> bool:
+        # Presence check for a regular file; a directory of the same name is not a file.
+        return self.path_of(name).is_file()
+
+    def subdirectories(self) -> tuple[Path, ...]:
+        # Sorted so a listing is stable across runs and filesystems. An absent root holds
+        # nothing, while a root that exists but cannot be scanned is a failure worth naming.
+        if not self._root.is_dir():
+            return ()
+        try:
+            return tuple(sorted(child for child in self._root.iterdir() if child.is_dir()))
+        except OSError as error:
+            raise LocalFileReadFailed(self._root.name, self.reason_for(error), error) from error
+
+    def read_text(self, name: str | Path) -> str | None:
+        # None means absent and nothing else; a file that exists but cannot be read or
+        # decoded raises, so a caller never mistakes a permission problem for a missing file.
+        path = self.path_of(name)
+        try:
+            return path.read_text(encoding="utf-8")
+        except FileNotFoundError:
+            return None
+        except (OSError, UnicodeError) as error:
+            raise LocalFileReadFailed(path.name, self.reason_for(error), error) from error
+
+    def read_json(self, name: str | Path) -> object | None:
+        # Same absent-versus-broken contract as read_text, with invalid JSON counted as broken.
+        body = self.read_text(name)
+        if body is None:
+            return None
+        try:
+            parsed: object = json.loads(body)
+        except ValueError as error:
+            path = self.path_of(name)
+            raise LocalFileReadFailed(path.name, self.reason_for(error), error) from error
+        return parsed
+
+    def write_json(self, name: str | Path, payload: object) -> Path:
+        # Serializes first so a malformed payload fails before the target file is touched.
+        return self.write_text(name, json.dumps(payload))
+
+    def write_text(self, name: str | Path, body: str) -> Path:
+        # Writes through a temp sibling plus os.replace, so a reader never sees a partial file
+        # and a crash mid-write leaves the previous version intact rather than a truncated one.
+        target = self.path_of(name)
+        temporary: str | None = None
+        try:
+            target.parent.mkdir(parents=True, exist_ok=True)
+            handle, temporary = tempfile.mkstemp(
+                dir=str(target.parent), prefix=f".{target.name}.", suffix=".tmp"
+            )
+            with os.fdopen(handle, "w", encoding="utf-8") as stream:
+                stream.write(body)
+            os.replace(temporary, target)
+            return target
+        except (OSError, UnicodeError) as error:
+            self._discard(temporary)
+            raise LocalFileWriteFailed(target.name, self.reason_for(error), error) from error
+
+    def append_line(self, name: str | Path, body: str) -> Path:
+        # Append is deliberately not atomic: an append-only log is read by outside tools that
+        # tail it, and rewriting it per record would break every reader holding an offset.
+        path = self.path_of(name)
+        try:
+            path.parent.mkdir(parents=True, exist_ok=True)
+            with path.open("a", encoding="utf-8") as stream:
+                stream.write(f"{body}\n")
+        except (OSError, UnicodeError) as error:
+            raise LocalFileWriteFailed(path.name, self.reason_for(error), error) from error
+        return path
+
+    def copy_into(self, name: str | Path, destination: Path) -> Path:
+        # Duplicates rather than moves or links, so the source stays readable and unchanged
+        # whatever the copy goes on to become.
+        try:
+            destination.parent.mkdir(parents=True, exist_ok=True)
+            shutil.copyfile(self.path_of(name), destination)
+        except OSError as error:
+            raise LocalFileWriteFailed(destination.name, self.reason_for(error), error) from error
+        return destination
+
+    @staticmethod
+    def reason_for(error: BaseException) -> str:
+        # A fixed category rather than the operating system's own message, so no absolute
+        # path or platform wording reaches an error, and the category alone names the repair.
+        # UnicodeError precedes ValueError because it is the more specific subclass.
+        match error:
+            case FileNotFoundError():
+                return "the file or one of its parent directories does not exist"
+            case PermissionError():
+                return "permission was denied"
+            case IsADirectoryError():
+                return "the path names a directory, not a file"
+            case NotADirectoryError() | FileExistsError():
+                return "a parent of the path is a file, not a directory"
+            case UnicodeError():
+                return "the content is not valid UTF-8 text"
+            case ValueError():
+                return "the content is not valid JSON"
+            case OSError() if error.errno == errno.ENOSPC:
+                return "the volume is full"
+            case OSError() if error.errno == errno.EROFS:
+                return "the volume is read-only"
+            case RuntimeError():
+                return "the path could not be resolved, such as an unexpandable ~ or a link loop"
+            case _:
+                return "the operating system refused the operation"
+
+    @staticmethod
+    def _discard(temporary: str | None) -> None:
+        # Only this call's own temp sibling is ever removed, never the destination.
+        if temporary is None:
+            return
+        try:
+            os.unlink(temporary)
+        except OSError:
+            pass

vidbyte_cli/lib/io/__init__.py

@@ -0,0 +1,16 @@
+"""Public process-I/O contracts: streams, terminal capabilities, prompts, and attachments."""
+
+from .attachments import AttachmentResolver
+from .codex_attachments import CodexAttachmentInputBuilder
+from .prompt import PromptInputResolver
+from .streams import IOStreams
+from .terminal import TerminalCapabilities, TerminalPolicy
+
+__all__ = [
+    "AttachmentResolver",
+    "CodexAttachmentInputBuilder",
+    "IOStreams",
+    "PromptInputResolver",
+    "TerminalCapabilities",
+    "TerminalPolicy",
+]

vidbyte_cli/lib/io/attachments.py

@@ -0,0 +1,129 @@
+"""Resolves explicit local agent attachments into bounded immutable snapshots.
+
+This module owns generic filesystem access for future agent commands. It does not attach an
+option to a command, launch a provider, or expand directories and globs.
+"""
+
+from __future__ import annotations
+
+import hashlib
+from pathlib import Path
+
+from ...types.attachments import AgentAttachment, AttachmentBundle, AttachmentKind
+from ..constants.runtime import AttachmentImageSuffix, AttachmentLimit
+from ..errors.failures import (
+    AttachmentDirectory,
+    AttachmentDuplicate,
+    AttachmentEmpty,
+    AttachmentFileNotFound,
+    AttachmentInputInvalid,
+    AttachmentLimitExceeded,
+    AttachmentTooLarge,
+    AttachmentUnreadable,
+    AttachmentUnsupported,
+)
+
+
+class AttachmentResolver:
+    """Reads an ordered, explicit set of files into one validated attachment bundle."""
+
+    def resolve(self, paths: tuple[Path, ...]) -> AttachmentBundle:
+        # Validates collection shape and limits before touching any caller path.
+        self._validate_input(paths)
+        if not paths:
+            return AttachmentBundle()
+        items: list[AgentAttachment] = []
+        seen: set[Path] = set()
+        total_bytes = 0
+        for path in paths:
+            item = self._resolve_one(path, seen, total_bytes)
+            total_bytes += item.size_bytes
+            if total_bytes > int(AttachmentLimit.MAX_TOTAL_BYTES):
+                raise AttachmentLimitExceeded()
+            items.append(item)
+        return AttachmentBundle(items=tuple(items), total_bytes=total_bytes)
+
+    def _validate_input(self, paths: tuple[Path, ...]) -> None:
+        # Rejects values outside Click's tuple-of-Path contract before accidental iteration.
+        if not isinstance(paths, tuple) or any(not isinstance(path, Path) for path in paths):
+            raise AttachmentInputInvalid()
+        if len(paths) > int(AttachmentLimit.MAX_FILES):
+            raise AttachmentLimitExceeded()
+
+    def _resolve_one(self, path: Path, seen: set[Path], total_bytes: int) -> AgentAttachment:
+        # Resolves one file, hashes its exact bytes, and classifies it without a second read.
+        resolved = self._resolved_path(path)
+        if resolved in seen:
+            raise AttachmentDuplicate()
+        seen.add(resolved)
+        raw = self._read_bytes(resolved)
+        size_bytes = len(raw)
+        if size_bytes == 0:
+            raise AttachmentEmpty()
+        if size_bytes > int(AttachmentLimit.MAX_FILE_BYTES):
+            raise AttachmentTooLarge()
+        if total_bytes + size_bytes > int(AttachmentLimit.MAX_TOTAL_BYTES):
+            raise AttachmentLimitExceeded()
+        digest = hashlib.sha256(raw).hexdigest()
+        if self._is_image(resolved):
+            return AgentAttachment(
+                supplied_path=path,
+                resolved_path=resolved,
+                name=path.name,
+                kind=AttachmentKind.IMAGE,
+                size_bytes=size_bytes,
+                sha256=digest,
+            )
+        content = self._decode_text(raw)
+        return AgentAttachment(
+            supplied_path=path,
+            resolved_path=resolved,
+            name=path.name,
+            kind=AttachmentKind.TEXT,
+            size_bytes=size_bytes,
+            sha256=digest,
+            content=content,
+        )
+
+    def _resolved_path(self, path: Path) -> Path:
+        # Converts path errors into a stable typed failure without exposing private paths.
+        try:
+            resolved = path.expanduser().resolve(strict=False)
+        except (OSError, RuntimeError) as error:
+            raise AttachmentUnreadable() from error
+        try:
+            if not resolved.exists():
+                raise AttachmentFileNotFound()
+            if resolved.is_dir():
+                raise AttachmentDirectory()
+            if not resolved.is_file():
+                raise AttachmentUnreadable()
+        except OSError as error:
+            raise AttachmentUnreadable() from error
+        return resolved
+
+    def _read_bytes(self, path: Path) -> bytes:
+        # Reads one exact snapshot and hides filesystem details from the public failure.
+        try:
+            return path.read_bytes()
+        except OSError as error:
+            raise AttachmentUnreadable() from error
+
+    def _is_image(self, path: Path) -> bool:
+        # Uses the closed suffix enum so provider-native image support cannot drift silently.
+        return path.suffix.lower() in {item.value for item in AttachmentImageSuffix}
+
+    def _decode_text(self, raw: bytes) -> str:
+        # Accepts UTF-8 with an optional BOM and rejects binary-looking text with NUL bytes.
+        try:
+            content = raw.decode("utf-8-sig")
+        except UnicodeDecodeError as error:
+            raise AttachmentUnsupported() from error
+        if "\x00" in content:
+            raise AttachmentUnsupported()
+        if not content:
+            raise AttachmentEmpty()
+        return content
+
+
+__all__ = ["AttachmentResolver"]

vidbyte_cli/lib/io/codex_attachments.py

@@ -0,0 +1,47 @@
+"""Converts provider-neutral attachment snapshots into native Codex run inputs.
+
+The SDK stays behind a lazy import boundary so importing the shared attachment layer never
+starts provider work or makes `--help` depend on Codex being installed.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from ...types.attachments import AgentAttachment, AttachmentBundle, AttachmentKind
+
+
+class CodexAttachmentInputBuilder:
+    """Builds one CodexRunInput from a prompt and an already-resolved attachment bundle."""
+
+    def build(self, prompt: str, bundle: AttachmentBundle) -> Any:
+        # Imports occur only when a future Codex service actually starts an agent turn.
+        from vidbyte.context.primitives import FileContextItem
+        from vidbyte.lib.dataclasses.codex import (
+            CodexLocalImageInput,
+            CodexRunInput,
+            CodexTextInput,
+        )
+
+        inputs: list[Any] = [CodexTextInput(prompt)]
+        context_items: list[Any] = []
+        for attachment in bundle.items:
+            if attachment.kind is AttachmentKind.IMAGE:
+                inputs.append(CodexLocalImageInput(str(attachment.resolved_path)))
+            else:
+                context_items.append(self._file_context(FileContextItem, attachment))
+        return CodexRunInput(items=tuple(inputs), context_items=tuple(context_items))
+
+    def _file_context(self, file_type: type[Any], attachment: AgentAttachment) -> Any:
+        # Reuses the resolver's bytes and hash rather than reading a changed file again.
+        return file_type(
+            path=str(attachment.supplied_path),
+            absolute_path=str(attachment.resolved_path),
+            size_bytes=attachment.size_bytes,
+            content=attachment.content,
+            language=attachment.resolved_path.suffix.lstrip(".") or None,
+            metadata={"sha256": attachment.sha256},
+        )
+
+
+__all__ = ["CodexAttachmentInputBuilder"]

vidbyte_cli/lib/io/prompt.py

@@ -0,0 +1,71 @@
+"""Exactly one prompt source per run: a positional value, a UTF-8 file, or explicit stdin.
+
+Two rules drive the shape. Sources are exclusive and checked before anything is opened, so
+an ambiguous command line can never quietly resolve one way. And stdin is read only for the
+literal `-` marker, so a command whose input happens to be redirected fails fast instead of
+blocking on a read that will never complete.
+
+Reads take one character past the limit: that detects oversized input without pulling an
+arbitrarily large file into memory. Error prose reports lengths, never prompt content.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from ..errors.failures import (
+    AmbiguousPromptSource,
+    EmptyPrompt,
+    MissingPrompt,
+    PromptFileNotUtf8,
+    PromptFileUnreadable,
+    PromptTooLong,
+    StandardInputNotText,
+)
+from .streams import IOStreams
+
+_DEFAULT_MAX_CHARS = 20_000
+
+
+class PromptInputResolver:
+    """Bounded resolver for explicit text, file, or stdin prompt input."""
+
+    def __init__(self, streams: IOStreams, max_chars: int = _DEFAULT_MAX_CHARS) -> None:
+        self._streams = streams
+        self._max_chars = max_chars
+
+    def resolve(self, positional: str | None, prompt_file: str | None) -> str:
+        # Reject ambiguity before reading either external source.
+        if positional is not None and prompt_file is not None:
+            raise AmbiguousPromptSource()
+        if positional is None and prompt_file is None:
+            raise MissingPrompt()
+        if prompt_file is not None:
+            return self._read_file(Path(prompt_file))
+        if positional == "-":
+            return self._read_stdin()
+        return self._validate(positional or "")
+
+    def _read_file(self, path: Path) -> str:
+        # UTF-8 is explicit so machine behavior does not depend on the host locale.
+        try:
+            with path.open("r", encoding="utf-8") as handle:
+                return self._validate(handle.read(self._max_chars + 1))
+        except UnicodeDecodeError as error:
+            raise PromptFileNotUtf8(error) from error
+        except (OSError, ValueError) as error:
+            raise PromptFileUnreadable(str(path), error) from error
+
+    def _read_stdin(self) -> str:
+        # Explicit stdin remains bounded and decoding failures stay safe usage errors.
+        try:
+            return self._validate(self._streams.stdin.read(self._max_chars + 1))
+        except UnicodeError as error:
+            raise StandardInputNotText(error) from error
+
+    def _validate(self, value: str) -> str:
+        if not value.strip():
+            raise EmptyPrompt()
+        if len(value) > self._max_chars:
+            raise PromptTooLong(self._max_chars)
+        return value

vidbyte_cli/lib/io/streams.py

@@ -0,0 +1,37 @@
+"""The process channels one CLI invocation writes to, as an injected dependency.
+
+Reusable code never touches `sys.stdout`/`sys.stderr` directly, so the CLI can be embedded,
+redirected, or captured without monkey-patching `sys`. Formatting policy (human vs JSON,
+color) is deliberately NOT here — `lib/output` owns it.
+"""
+
+from __future__ import annotations
+
+import sys
+from dataclasses import dataclass
+from typing import TextIO
+
+
+@dataclass(frozen=True)
+class IOStreams:
+    """The stdin/stdout/stderr triple owned by one invocation."""
+
+    stdin: TextIO
+    stdout: TextIO
+    stderr: TextIO
+
+    @classmethod
+    def system(cls) -> IOStreams:
+        # Bound at invocation time, not import time, so redirection set up by an embedding
+        # caller after `import vidbyte_cli` is still honoured.
+        return cls(stdin=sys.stdin, stdout=sys.stdout, stderr=sys.stderr)
+
+    def write_output(self, message: str) -> None:
+        # Results go to stdout so shell pipelines stay dependable.
+        self.stdout.write(f"{message}\n")
+        self.stdout.flush()
+
+    def write_error(self, message: str) -> None:
+        # Diagnostics go to stderr so a failure can't corrupt structured stdout.
+        self.stderr.write(f"{message}\n")
+        self.stderr.flush()